@wrikka/create-docs 0.1.0

package/src/modules/i18n/types/locale.ts

@@ -0,0 +1,17 @@
+/**
+ * Locale types for i18n support.
+ */
+
+export type Locale = string;
+
+export type LocaleConfig = {
+	readonly defaultLocale: Locale;
+	readonly locales: readonly Locale[];
+	readonly localePaths: Readonly<Record<Locale, string>>;
+};
+
+export type LocalizedDocPage = {
+	readonly locale: Locale;
+	readonly slug: string;
+	readonly originalSlug: string;
+};

package/src/modules/image-optimization/application/sharp-adapter.ts

@@ -0,0 +1,58 @@
+/**
+ * Sharp adapter implementation.
+ * Provides image optimization using the sharp library.
+ */
+
+import { configError, ioError } from "@create-docs/shared/errors";
+import type { ImageOptimizerPort } from "../ports/image-optimizer-port";
+import type { ImageConfig } from "../types/image";
+
+const SHARP_MISSING_ERROR =
+	"sharp is not installed. Image optimization requires the sharp package and native image libraries.";
+
+const validateImageConfig = (config: unknown): ImageConfig => {
+	const cfg = config as Partial<ImageConfig> | undefined;
+
+	if (!cfg?.formats?.length) {
+		throw configError("Image optimization config requires formats", {
+			context: { config: cfg },
+			hint: "Provide formats (e.g. ['webp']).",
+		});
+	}
+
+	if (!cfg?.widths?.length) {
+		throw configError("Image optimization config requires widths", {
+			context: { config: cfg },
+			hint: "Provide widths (e.g. [640, 1024]).",
+		});
+	}
+
+	if (cfg.quality == null || cfg.quality < 1 || cfg.quality > 100) {
+		throw configError(
+			"Image optimization config requires a quality between 1 and 100",
+			{
+				context: { config: cfg },
+			},
+		);
+	}
+
+	return cfg as ImageConfig;
+};
+
+export const createSharpAdapter = (): ImageOptimizerPort => ({
+	optimize: async (imagePath: string, config?: unknown) => {
+		try {
+			validateImageConfig(config);
+			throw ioError(imagePath, SHARP_MISSING_ERROR);
+		} catch (error) {
+			if (error && typeof error === "object" && "kind" in error) {
+				throw error;
+			}
+			throw ioError(imagePath, SHARP_MISSING_ERROR);
+		}
+	},
+
+	getMetadata: async (imagePath: string) => {
+		throw ioError(imagePath, SHARP_MISSING_ERROR);
+	},
+});

package/src/modules/image-optimization/domain/events/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Domain events for image optimization
+ */
+export interface OptimizationStartedEvent {
+	readonly type: "OPTIMIZATION_STARTED";
+	readonly timestamp: number;
+	readonly imagePath: string;
+}
+
+export interface OptimizationCompletedEvent {
+	readonly type: "OPTIMIZATION_COMPLETED";
+	readonly timestamp: number;
+	readonly imagePath: string;
+	readonly sizeReduction: number;
+}
+
+export type ImageOptimizationDomainEvent =
+	| OptimizationStartedEvent
+	| OptimizationCompletedEvent;
+
+export const createOptimizationStartedEvent = (
+	imagePath: string,
+	now: number = Date.now(),
+): OptimizationStartedEvent => ({
+	type: "OPTIMIZATION_STARTED",
+	timestamp: now,
+	imagePath,
+});
+
+export const createOptimizationCompletedEvent = (
+	imagePath: string,
+	sizeReduction: number,
+	now: number = Date.now(),
+): OptimizationCompletedEvent => ({
+	type: "OPTIMIZATION_COMPLETED",
+	timestamp: now,
+	imagePath,
+	sizeReduction,
+});

package/src/modules/image-optimization/domain/models/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Domain models for image optimization
+ */
+export interface ImageOptimization {
+	readonly originalPath: string;
+	readonly optimizedPath: string;
+	readonly originalSize: number;
+	readonly optimizedSize: number;
+	readonly format: "webp" | "avif" | "png" | "jpg";
+	readonly quality: number;
+}
+
+export const createImageOptimization = (
+	originalPath: string,
+	optimizedPath: string,
+	originalSize: number,
+	optimizedSize: number,
+	format: ImageOptimization["format"],
+	quality: number,
+): ImageOptimization => ({
+	originalPath,
+	optimizedPath,
+	originalSize,
+	optimizedSize,
+	format,
+	quality,
+});

package/src/modules/image-optimization/domain/operations/image-operations.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure image optimization 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 { ImageConfig, OptimizedImage } from "../../types/image";
+
+export type ImageOptimizationError = {
+	readonly kind: "image-optimization-error";
+	readonly message: string;
+};
+
+/**
+ * Generate srcset for responsive images.
+ */
+export const generateSrcset = (
+	baseSrc: string,
+	widths: readonly number[],
+): string => {
+	return widths.map((width) => `${baseSrc}?w=${width} ${width}w`).join(", ");
+};
+
+/**
+ * Calculate aspect ratio from dimensions.
+ */
+export const calculateAspectRatio = (width: number, height: number): number => {
+	return width / height;
+};
+
+/**
+ * Validate image config.
+ */
+export const validateImageConfig = (config: ImageConfig): boolean => {
+	if (config.formats.length === 0) return false;
+	if (config.widths.length === 0) return false;
+	if (config.quality < 0 || config.quality > 100) return false;
+	return true;
+};
+
+/**
+ * Process image metadata.
+ */
+export const processImageMetadata = (
+	_metadata: unknown,
+	_config: ImageConfig,
+): Result<OptimizedImage, ImageOptimizationError> => {
+	try {
+		// This will be implemented via adapter
+		// For now, return a basic optimized image
+		return ok({
+			src: "",
+			srcset: "",
+			width: 0,
+			height: 0,
+			format: "webp",
+		});
+	} catch (error) {
+		return err({
+			kind: "image-optimization-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};

package/src/modules/image-optimization/domain/validators/index.ts

@@ -0,0 +1,52 @@
+// Image Optimization Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Image Path Schema
+ */
+export const imagePathSchema: Type = type("string >= 1");
+
+export type ImagePath = typeof imagePathSchema.infer;
+
+/**
+ * Quality Schema
+ */
+export const qualitySchema: Type = type("number >= 0").narrow(
+	(quality: number) => quality <= 100,
+);
+
+export type Quality = typeof qualitySchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate image path using Arktype
+ */
+export const validateImagePath = (path: unknown): ImagePath => {
+	const result = imagePathSchema(path);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Image path must be a non-empty string");
+	}
+	return result as ImagePath;
+};
+
+/**
+ * Validate quality using Arktype
+ */
+export const validateQuality = (quality: unknown): Quality => {
+	const result = qualitySchema(quality);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Quality must be a number between 0 and 100");
+	}
+	return result as Quality;
+};

package/src/modules/image-optimization/index.ts

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

package/src/modules/image-optimization/ports/image-optimizer-port.ts

@@ -0,0 +1,15 @@
+/**
+ * Port for image optimization operations.
+ */
+
+export type ImageOptimizerPort = {
+	/**
+	 * Optimize image with specified formats and widths.
+	 */
+	readonly optimize: (imagePath: string, config: unknown) => Promise<unknown>;
+
+	/**
+	 * Get image metadata.
+	 */
+	readonly getMetadata: (imagePath: string) => Promise<unknown>;
+};

package/src/modules/image-optimization/types/image.ts

@@ -0,0 +1,17 @@
+/**
+ * Image optimization types for image processing pipeline.
+ */
+
+export type ImageConfig = {
+	readonly formats: readonly ("webp" | "avif" | "jpeg" | "png")[];
+	readonly widths: readonly number[];
+	readonly quality: number;
+};
+
+export type OptimizedImage = {
+	readonly src: string;
+	readonly srcset: string;
+	readonly width: number;
+	readonly height: number;
+	readonly format: string;
+};

package/src/modules/live-editor/application/usecases/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Live Editor Use Cases
+ *
+ * Orchestration layer for live editor operations
+ */
+
+import type { CommitOptions, GitAdapter, PushOptions } from "../../ports";
+import type { EditorState } from "../../types";
+
+/**
+ * Load editor state
+ */
+export const loadEditorState = async (
+	git: GitAdapter,
+	_filePath: string,
+): Promise<EditorState> => {
+	try {
+		const gitStatus = await git.getStatus();
+
+		return {
+			mode: "split",
+			currentFile: null, // Will be loaded separately
+			gitStatus,
+			loading: false,
+		};
+	} catch (error) {
+		return {
+			mode: "split",
+			currentFile: null,
+			gitStatus: null,
+			loading: false,
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+};
+
+/**
+ * Commit and push changes
+ */
+export const commitAndPush = async (
+	git: GitAdapter,
+	options: CommitOptions & { push?: boolean; pushOptions?: PushOptions },
+): Promise<void> => {
+	await git.commit(options);
+
+	if (options.push) {
+		await git.push(options.pushOptions);
+	}
+};
+
+/**
+ * Save file
+ */
+export const saveFile = async (
+	fileSystem: { writeFile: (path: string, content: string) => Promise<void> },
+	filePath: string,
+	content: string,
+): Promise<void> => {
+	await fileSystem.writeFile(filePath, content);
+};

package/src/modules/live-editor/domain/events/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Domain events for live editor
+ */
+export interface ContentChangedEvent {
+	readonly type: "CONTENT_CHANGED";
+	readonly timestamp: number;
+	readonly contentLength: number;
+}
+
+export interface CursorMovedEvent {
+	readonly type: "CURSOR_MOVED";
+	readonly timestamp: number;
+	readonly line: number;
+	readonly column: number;
+}
+
+export type LiveEditorDomainEvent = ContentChangedEvent | CursorMovedEvent;
+
+export const createContentChangedEvent = (
+	contentLength: number,
+	now: number = Date.now(),
+): ContentChangedEvent => ({
+	type: "CONTENT_CHANGED",
+	timestamp: now,
+	contentLength,
+});
+
+export const createCursorMovedEvent = (
+	line: number,
+	column: number,
+	now: number = Date.now(),
+): CursorMovedEvent => ({
+	type: "CURSOR_MOVED",
+	timestamp: now,
+	line,
+	column,
+});

package/src/modules/live-editor/domain/gitOperations.ts

@@ -0,0 +1,110 @@
+/**
+ * Git Operations
+ *
+ * Pure functions for Git operations using simple-git
+ */
+
+import type { SimpleGit } from "simple-git";
+import type { CommitOptions, GitStatus, PushOptions } from "../types";
+
+interface GitFile {
+	path: string;
+	index: string;
+	working_dir: string;
+}
+
+/**
+ * Get current branch name
+ */
+export const getCurrentBranch = async (git: SimpleGit): Promise<string> => {
+	const branch = await git.branch();
+	return branch.current;
+};
+
+/**
+ * Get git status
+ */
+export const getGitStatus = async (git: SimpleGit): Promise<GitStatus> => {
+	const status = await git.status();
+	const branch = await getCurrentBranch(git);
+
+	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),
+	};
+};
+
+/**
+ * Commit changes
+ */
+export const commitChanges = async (
+	git: SimpleGit,
+	options: CommitOptions,
+): Promise<void> => {
+	await git.add(".");
+	if (options.author && options.email) {
+		await git.commit([
+			options.message,
+			"--author",
+			`${options.author} <${options.email}>`,
+		]);
+	} else {
+		await git.commit(options.message);
+	}
+};
+
+/**
+ * Push changes
+ */
+export const pushChanges = async (
+	git: SimpleGit,
+	options: PushOptions = {},
+): Promise<void> => {
+	const remote = options.remote || "origin";
+	const branch = options.branch || (await getCurrentBranch(git));
+
+	if (options.force) {
+		await git.push(["--force", remote, branch]);
+	} else {
+		await git.push(remote, branch);
+	}
+};
+
+/**
+ * Stage file
+ */
+export const stageFile = async (
+	git: SimpleGit,
+	path: string,
+): Promise<void> => {
+	await git.add(path);
+};
+
+/**
+ * Unstage file
+ */
+export const unstageFile = async (
+	git: SimpleGit,
+	path: string,
+): Promise<void> => {
+	await git.reset(["--mixed", path]);
+};
+
+/**
+ * Discard changes
+ */
+export const discardChanges = async (
+	git: SimpleGit,
+	path: string,
+): Promise<void> => {
+	await git.checkout(["--", path]);
+};

package/src/modules/live-editor/domain/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Live Editor Domain
+ *
+ * Pure business logic for live editor operations
+ */
+
+export {
+	commitChanges,
+	discardChanges,
+	getCurrentBranch,
+	getGitStatus,
+	pushChanges,
+	stageFile,
+	unstageFile,
+} from "./gitOperations";

package/src/modules/live-editor/domain/models/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Domain models for live editor
+ */
+export interface EditorState {
+	readonly content: string;
+	readonly language: string;
+	readonly cursorPosition: { line: number; column: number };
+	readonly selection?: { start: number; end: number };
+}
+
+export const createEditorState = (
+	content: string,
+	language: string,
+	cursorPosition: { line: number; column: number },
+	options?: { selection?: { start: number; end: number } },
+): EditorState => ({
+	content,
+	language,
+	cursorPosition,
+	selection: options?.selection,
+});

package/src/modules/live-editor/domain/validators/index.ts

@@ -0,0 +1,55 @@
+// Live Editor Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Content Schema
+ */
+export const contentSchema: Type = type("string");
+
+export type Content = typeof contentSchema.infer;
+
+/**
+ * Cursor Position Schema
+ */
+export const cursorPositionSchema: Type = type({
+	line: "number >= 0",
+	column: "number >= 0",
+});
+
+export type CursorPosition = typeof cursorPositionSchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate content using Arktype
+ */
+export const validateContent = (content: unknown): Content => {
+	const result = contentSchema(content);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Content must be a string");
+	}
+	return result as Content;
+};
+
+/**
+ * Validate cursor position using Arktype
+ */
+export const validateCursorPosition = (position: unknown): CursorPosition => {
+	const result = cursorPositionSchema(position);
+	if (result instanceof type.errors) {
+		throw new ValidationError(
+			"Cursor position must be a valid object with line and column",
+		);
+	}
+	return result as CursorPosition;
+};

package/src/modules/live-editor/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Live Editor Module
+ *
+ * Live editor with Git integration for documentation
+ */
+
+export {
+	commitAndPush,
+	loadEditorState,
+	saveFile,
+} from "./application/usecases";
+export * from "./domain";
+export * from "./ports";
+export * from "./types";

package/src/modules/live-editor/ports/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Live Editor Ports
+ *
+ * Module-specific interfaces for live editor
+ */
+
+import type {
+	CommitOptions,
+	FileContent,
+	GitStatus,
+	PushOptions,
+} from "../types";
+
+/**
+ * Git adapter interface
+ */
+export interface GitAdapter {
+	/** Get current branch */
+	getCurrentBranch(): Promise<string>;
+	/** Get git status */
+	getStatus(): Promise<GitStatus>;
+	/** Commit changes */
+	commit(options: CommitOptions): Promise<void>;
+	/** Push changes */
+	push(options?: PushOptions): Promise<void>;
+	/** Stage file */
+	stageFile(path: string): Promise<void>;
+	/** Unstage file */
+	unstageFile(path: string): Promise<void>;
+	/** Discard changes */
+	discardChanges(path: string): Promise<void>;
+}
+
+/**
+ * File system adapter interface
+ */
+export interface FileSystemAdapter {
+	/** Read file */
+	readFile(path: string): Promise<string>;
+	/** Write file */
+	writeFile(path: string, content: string): Promise<void>;
+	/** Watch file */
+	watchFile(path: string, callback: (content: string) => void): () => void;
+	/** Get file stats */
+	getFileStats(path: string): Promise<{ mtimeMs: number; size: number }>;
+}
+
+// Re-export types for convenience
+export type { CommitOptions, FileContent, GitStatus, PushOptions };