@wrikka/create-docs 0.1.0

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

@@ -0,0 +1,55 @@
+/**
+ * Domain events for export
+ */
+export interface ExportStartedEvent {
+	readonly type: "EXPORT_STARTED";
+	readonly timestamp: number;
+	readonly format: string;
+	readonly filename: string;
+}
+
+export interface ExportCompletedEvent {
+	readonly type: "EXPORT_COMPLETED";
+	readonly timestamp: number;
+	readonly filePath: string;
+}
+
+export interface ExportFailedEvent {
+	readonly type: "EXPORT_FAILED";
+	readonly timestamp: number;
+	readonly error: string;
+}
+
+export type ExportDomainEvent =
+	| ExportStartedEvent
+	| ExportCompletedEvent
+	| ExportFailedEvent;
+
+export const createExportStartedEvent = (
+	format: string,
+	filename: string,
+	now: number = Date.now(),
+): ExportStartedEvent => ({
+	type: "EXPORT_STARTED",
+	timestamp: now,
+	format,
+	filename,
+});
+
+export const createExportCompletedEvent = (
+	filePath: string,
+	now: number = Date.now(),
+): ExportCompletedEvent => ({
+	type: "EXPORT_COMPLETED",
+	timestamp: now,
+	filePath,
+});
+
+export const createExportFailedEvent = (
+	error: string,
+	now: number = Date.now(),
+): ExportFailedEvent => ({
+	type: "EXPORT_FAILED",
+	timestamp: now,
+	error,
+});

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

@@ -0,0 +1,38 @@
+/**
+ * Domain models for export
+ */
+export interface ExportConfig {
+	readonly format: "pdf" | "html" | "markdown" | "json";
+	readonly includeImages: boolean;
+	readonly includeCodeBlocks: boolean;
+	readonly filename: string;
+}
+
+export interface ExportResult {
+	readonly success: boolean;
+	readonly filePath?: string;
+	readonly error?: string;
+	readonly timestamp: number;
+}
+
+export const createExportConfig = (
+	format: ExportConfig["format"],
+	filename: string,
+	options?: { includeImages?: boolean; includeCodeBlocks?: boolean },
+): ExportConfig => ({
+	format,
+	filename,
+	includeImages: options?.includeImages ?? true,
+	includeCodeBlocks: options?.includeCodeBlocks ?? true,
+});
+
+export const createExportResult = (
+	success: boolean,
+	options?: { filePath?: string; error?: string; timestamp?: number },
+	now: number = Date.now(),
+): ExportResult => ({
+	success,
+	filePath: options?.filePath,
+	error: options?.error,
+	timestamp: options?.timestamp ?? now,
+});

package/src/modules/export/domain/operations/export-operations.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure export 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 { ExportConfig, ExportResult } from "../../types/export";
+
+export type ExportError = {
+	readonly kind: "export-error";
+	readonly message: string;
+};
+
+/**
+ * Validate export config.
+ */
+export const validateExportConfig = (config: ExportConfig): boolean => {
+	if (!config.format) return false;
+	if (!config.outputDir) return false;
+	return true;
+};
+
+/**
+ * Generate export filename.
+ */
+export const generateExportFilename = (
+	slug: string,
+	format: "pdf" | "epub",
+	now: number = Date.now(),
+): string => {
+	const timestamp = new Date(now).toISOString().split("T")[0];
+	return `${slug}-${timestamp}.${format}`;
+};
+
+/**
+ * Process export result.
+ */
+export const processExportResult = (
+	success: boolean,
+	outputPath: string,
+	error: string | null,
+): Result<ExportResult, ExportError> => {
+	try {
+		return ok({
+			success,
+			outputPath,
+			error,
+		});
+	} catch (error) {
+		return err({
+			kind: "export-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};

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

@@ -0,0 +1,52 @@
+// Export Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Export Format Schema
+ */
+export const exportFormatSchema: Type = type(
+	"'pdf' | 'html' | 'markdown' | 'json'",
+);
+
+export type ExportFormat = typeof exportFormatSchema.infer;
+
+/**
+ * Filename Schema
+ */
+export const filenameSchema: Type = type("string >= 1");
+
+export type Filename = typeof filenameSchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate export format using Arktype
+ */
+export const validateExportFormat = (format: unknown): ExportFormat => {
+	const result = exportFormatSchema(format);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Invalid export format");
+	}
+	return result as ExportFormat;
+};
+
+/**
+ * Validate filename using Arktype
+ */
+export const validateFilename = (filename: unknown): Filename => {
+	const result = filenameSchema(filename);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Filename must be a non-empty string");
+	}
+	return result as Filename;
+};

package/src/modules/export/index.ts

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

package/src/modules/export/ports/export-port.ts

@@ -0,0 +1,15 @@
+/**
+ * Port for export operations.
+ */
+
+export type ExportPort = {
+	/**
+	 * Export documentation to PDF.
+	 */
+	readonly exportToPdf: (content: string, config: unknown) => Promise<unknown>;
+
+	/**
+	 * Export documentation to EPUB.
+	 */
+	readonly exportToEpub: (content: string, config: unknown) => Promise<unknown>;
+};

package/src/modules/export/types/export.ts

@@ -0,0 +1,15 @@
+/**
+ * Export types for PDF/EPUB export functionality.
+ */
+
+export type ExportConfig = {
+	readonly format: "pdf" | "epub";
+	readonly outputDir: string;
+	readonly includeImages: boolean;
+};
+
+export type ExportResult = {
+	readonly success: boolean;
+	readonly outputPath: string;
+	readonly error: string | null;
+};

package/src/modules/external-search/application/algolia-adapter.ts

@@ -0,0 +1,182 @@
+/**
+ * Algolia adapter implementation.
+ * Provides Algolia search integration via the REST API.
+ */
+
+import { configError, pluginError } from "@create-docs/shared/errors";
+import type { ExternalSearchPort } from "../ports/external-search-port";
+import type {
+	ExternalSearchConfig,
+	ExternalSearchResult,
+} from "../types/search";
+
+export const createAlgoliaAdapter = (
+	appId: string,
+	_apiKey: string,
+): ExternalSearchPort => ({
+	search: async (query: string, config?: unknown) => {
+		const cfg = config as Partial<ExternalSearchConfig> | undefined;
+		const indexName = cfg?.indexName;
+		const apiKey = cfg?.apiKey ?? _apiKey;
+
+		if (!appId) {
+			throw configError("Algolia appId is required", {
+				context: { query, config },
+			});
+		}
+
+		if (!indexName) {
+			throw configError("Algolia indexName is required", {
+				context: { appId, query },
+				hint: "Set indexName in the search config.",
+			});
+		}
+
+		if (!apiKey) {
+			throw configError("Algolia API key is required", {
+				context: { appId, indexName, query },
+				hint: "Pass the API key to createAlgoliaAdapter or set apiKey in config.",
+			});
+		}
+
+		const searchHost = `https://${appId}-dsn.algolia.net`;
+		const url = `${searchHost}/1/indexes/${encodeURIComponent(indexName)}/query`;
+		const headers = {
+			"X-Algolia-Application-Id": appId,
+			"X-Algolia-API-Key": apiKey,
+			"Content-Type": "application/json",
+		};
+
+		try {
+			const response = await fetch(url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify({
+					params: `query=${encodeURIComponent(query)}&hitsPerPage=20`,
+				}),
+			});
+
+			if (!response.ok) {
+				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			}
+
+			const data = (await response.json()) as {
+				hits?: readonly ExternalSearchResult[];
+			};
+			return data.hits ?? [];
+		} catch (error) {
+			throw pluginError("Algolia search failed", {
+				context: { query, config, error: String(error) },
+			});
+		}
+	},
+
+	index: async (docs: readonly unknown[], config?: unknown) => {
+		const cfg = config as Partial<ExternalSearchConfig> | undefined;
+		const indexName = cfg?.indexName;
+		const apiKey = cfg?.apiKey ?? _apiKey;
+
+		if (!appId) {
+			throw configError("Algolia appId is required", {
+				context: { config },
+			});
+		}
+
+		if (!indexName) {
+			throw configError("Algolia indexName is required", {
+				context: { appId },
+				hint: "Set indexName in the search config.",
+			});
+		}
+
+		if (!apiKey) {
+			throw configError("Algolia API key is required", {
+				context: { appId, indexName },
+				hint: "Pass the API key to createAlgoliaAdapter or set apiKey in config.",
+			});
+		}
+
+		const writeHost = `https://${appId}.algolia.net`;
+		const url = `${writeHost}/1/indexes/${encodeURIComponent(indexName)}/batch`;
+		const headers = {
+			"X-Algolia-Application-Id": appId,
+			"X-Algolia-API-Key": apiKey,
+			"Content-Type": "application/json",
+		};
+
+		const requests = docs.map((doc) => ({
+			action: "addObject" as const,
+			body: doc,
+		}));
+
+		try {
+			const response = await fetch(url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify({ requests }),
+			});
+
+			if (!response.ok) {
+				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			}
+		} catch (error) {
+			throw pluginError("Algolia indexing failed", {
+				context: {
+					docCount: docs.length,
+					config,
+					error: String(error),
+				},
+			});
+		}
+	},
+
+	clear: async (config?: unknown) => {
+		const cfg = config as Partial<ExternalSearchConfig> | undefined;
+		const indexName = cfg?.indexName;
+		const apiKey = cfg?.apiKey ?? _apiKey;
+
+		if (!appId) {
+			throw configError("Algolia appId is required", {
+				context: { config },
+			});
+		}
+
+		if (!indexName) {
+			throw configError("Algolia indexName is required", {
+				context: { appId },
+				hint: "Set indexName in the search config.",
+			});
+		}
+
+		if (!apiKey) {
+			throw configError("Algolia API key is required", {
+				context: { appId, indexName },
+				hint: "Pass the API key to createAlgoliaAdapter or set apiKey in config.",
+			});
+		}
+
+		const writeHost = `https://${appId}.algolia.net`;
+		const url = `${writeHost}/1/indexes/${encodeURIComponent(indexName)}/clear`;
+		const headers = {
+			"X-Algolia-Application-Id": appId,
+			"X-Algolia-API-Key": apiKey,
+			"Content-Type": "application/json",
+		};
+
+		try {
+			const response = await fetch(url, {
+				method: "POST",
+				headers,
+				body: "{}",
+			});
+
+			if (!response.ok) {
+				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			}
+		} catch (error) {
+			throw pluginError("Algolia clear failed", {
+				context: { config, error: String(error) },
+			});
+		}
+	},
+});

package/src/modules/external-search/application/meilisearch-adapter.ts

@@ -0,0 +1,161 @@
+/**
+ * MeiliSearch adapter implementation.
+ * Provides MeiliSearch search integration via the REST API.
+ */
+
+import { configError, pluginError } from "@create-docs/shared/errors";
+import type { ExternalSearchPort } from "../ports/external-search-port";
+import type {
+	ExternalSearchConfig,
+	ExternalSearchResult,
+} from "../types/search";
+
+export const createMeilisearchAdapter = (
+	host: string,
+	_apiKey: string,
+): ExternalSearchPort => ({
+	search: async (query: string, config?: unknown) => {
+		const cfg = config as Partial<ExternalSearchConfig> | undefined;
+		const resolvedHost = (cfg?.host ?? host).replace(/\/+$/, "");
+		const indexName = cfg?.indexName;
+		const apiKey = cfg?.apiKey ?? _apiKey;
+
+		if (!resolvedHost) {
+			throw configError("MeiliSearch host is required", {
+				context: { query, config },
+				hint: "Pass host to createMeilisearchAdapter or set host in config.",
+			});
+		}
+
+		if (!indexName) {
+			throw configError("MeiliSearch indexName is required", {
+				context: { host: resolvedHost, query },
+				hint: "Set indexName in the search config.",
+			});
+		}
+
+		const url = `${resolvedHost}/indexes/${encodeURIComponent(indexName)}/search`;
+		const headers: Record<string, string> = {
+			"Content-Type": "application/json",
+		};
+
+		if (apiKey) {
+			headers.Authorization = `Bearer ${apiKey}`;
+		}
+
+		try {
+			const response = await fetch(url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify({ q: query, limit: 20 }),
+			});
+
+			if (!response.ok) {
+				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			}
+
+			const data = (await response.json()) as {
+				hits?: readonly ExternalSearchResult[];
+			};
+			return data.hits ?? [];
+		} catch (error) {
+			throw pluginError("MeiliSearch search failed", {
+				context: { query, config, host: resolvedHost, error: String(error) },
+			});
+		}
+	},
+
+	index: async (docs: readonly unknown[], config?: unknown) => {
+		const cfg = config as Partial<ExternalSearchConfig> | undefined;
+		const resolvedHost = (cfg?.host ?? host).replace(/\/+$/, "");
+		const indexName = cfg?.indexName;
+		const apiKey = cfg?.apiKey ?? _apiKey;
+
+		if (!resolvedHost) {
+			throw configError("MeiliSearch host is required", {
+				context: { config },
+				hint: "Pass host to createMeilisearchAdapter or set host in config.",
+			});
+		}
+
+		if (!indexName) {
+			throw configError("MeiliSearch indexName is required", {
+				context: { host: resolvedHost },
+				hint: "Set indexName in the search config.",
+			});
+		}
+
+		const url = `${resolvedHost}/indexes/${encodeURIComponent(indexName)}/documents`;
+		const headers: Record<string, string> = {
+			"Content-Type": "application/json",
+		};
+
+		if (apiKey) {
+			headers.Authorization = `Bearer ${apiKey}`;
+		}
+
+		try {
+			const response = await fetch(url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify(docs),
+			});
+
+			if (!response.ok) {
+				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			}
+		} catch (error) {
+			throw pluginError("MeiliSearch indexing failed", {
+				context: {
+					docCount: docs.length,
+					config,
+					host: resolvedHost,
+					error: String(error),
+				},
+			});
+		}
+	},
+
+	clear: async (config?: unknown) => {
+		const cfg = config as Partial<ExternalSearchConfig> | undefined;
+		const resolvedHost = (cfg?.host ?? host).replace(/\/+$/, "");
+		const indexName = cfg?.indexName;
+		const apiKey = cfg?.apiKey ?? _apiKey;
+
+		if (!resolvedHost) {
+			throw configError("MeiliSearch host is required", {
+				context: { config },
+				hint: "Pass host to createMeilisearchAdapter or set host in config.",
+			});
+		}
+
+		if (!indexName) {
+			throw configError("MeiliSearch indexName is required", {
+				context: { host: resolvedHost },
+				hint: "Set indexName in the search config.",
+			});
+		}
+
+		const url = `${resolvedHost}/indexes/${encodeURIComponent(indexName)}/documents`;
+		const headers: Record<string, string> = {};
+
+		if (apiKey) {
+			headers.Authorization = `Bearer ${apiKey}`;
+		}
+
+		try {
+			const response = await fetch(url, {
+				method: "DELETE",
+				headers,
+			});
+
+			if (!response.ok) {
+				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			}
+		} catch (error) {
+			throw pluginError("MeiliSearch clear failed", {
+				context: { config, host: resolvedHost, error: String(error) },
+			});
+		}
+	},
+});

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

@@ -0,0 +1,42 @@
+/**
+ * Domain events for external search
+ */
+export interface SearchRequestedEvent {
+	readonly type: "SEARCH_REQUESTED";
+	readonly timestamp: number;
+	readonly query: string;
+	readonly providerId: string;
+}
+
+export interface SearchCompletedEvent {
+	readonly type: "SEARCH_COMPLETED";
+	readonly timestamp: number;
+	readonly query: string;
+	readonly resultCount: number;
+}
+
+export type ExternalSearchDomainEvent =
+	| SearchRequestedEvent
+	| SearchCompletedEvent;
+
+export const createSearchRequestedEvent = (
+	query: string,
+	providerId: string,
+	now: number = Date.now(),
+): SearchRequestedEvent => ({
+	type: "SEARCH_REQUESTED",
+	timestamp: now,
+	query,
+	providerId,
+});
+
+export const createSearchCompletedEvent = (
+	query: string,
+	resultCount: number,
+	now: number = Date.now(),
+): SearchCompletedEvent => ({
+	type: "SEARCH_COMPLETED",
+	timestamp: now,
+	query,
+	resultCount,
+});

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

@@ -0,0 +1,42 @@
+/**
+ * Domain models for external search
+ */
+export interface SearchProvider {
+	readonly id: string;
+	readonly name: string;
+	readonly endpoint: string;
+	readonly enabled: boolean;
+}
+
+export interface SearchResult {
+	readonly providerId: string;
+	readonly title: string;
+	readonly url: string;
+	readonly snippet?: string;
+	readonly relevance: number;
+}
+
+export const createSearchProvider = (
+	id: string,
+	name: string,
+	endpoint: string,
+	enabled: boolean = true,
+): SearchProvider => ({
+	id,
+	name,
+	endpoint,
+	enabled,
+});
+
+export const createSearchResult = (
+	providerId: string,
+	title: string,
+	url: string,
+	options?: { snippet?: string; relevance?: number },
+): SearchResult => ({
+	providerId,
+	title,
+	url,
+	snippet: options?.snippet,
+	relevance: options?.relevance ?? 0,
+});