@wrikka/create-docs 0.1.0

package/src/modules/code-block-enhancements/domain/models/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Domain models for code block enhancements
+ */
+export interface CodeBlock {
+	readonly id: string;
+	readonly language: string;
+	readonly code: string;
+	readonly lineNumbers: boolean;
+	readonly syntaxHighlighting: boolean;
+}
+
+export interface CodeEnhancement {
+	readonly type: "copy" | "download" | "fullscreen" | "line-highlight";
+	readonly enabled: boolean;
+}
+
+export const createCodeBlock = (
+	id: string,
+	language: string,
+	code: string,
+	options?: { lineNumbers?: boolean; syntaxHighlighting?: boolean },
+): CodeBlock => ({
+	id,
+	language,
+	code,
+	lineNumbers: options?.lineNumbers ?? true,
+	syntaxHighlighting: options?.syntaxHighlighting ?? true,
+});
+
+export const createCodeEnhancement = (
+	type: CodeEnhancement["type"],
+	enabled: boolean,
+): CodeEnhancement => ({
+	type,
+	enabled,
+});

package/src/modules/code-block-enhancements/domain/validators/index.ts

@@ -0,0 +1,50 @@
+// Code Block Enhancements Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Language Schema
+ */
+export const languageSchema: Type = type("string >= 1");
+
+export type Language = typeof languageSchema.infer;
+
+/**
+ * Code Schema
+ */
+export const codeSchema: Type = type("string");
+
+export type Code = typeof codeSchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate language using Arktype
+ */
+export const validateLanguage = (language: unknown): Language => {
+	const result = languageSchema(language);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Language must be a non-empty string");
+	}
+	return result as Language;
+};
+
+/**
+ * Validate code using Arktype
+ */
+export const validateCode = (code: unknown): Code => {
+	const result = codeSchema(code);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Code must be a string");
+	}
+	return result as Code;
+};

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

@@ -0,0 +1,10 @@
+/**
+ * Code Block Enhancements Module
+ *
+ * Code block enhancements for documentation
+ */
+
+export { enhanceCodeBlocks } from "./application/usecases";
+export * from "./domain";
+export * from "./ports";
+export * from "./types";

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

@@ -0,0 +1,18 @@
+/**
+ * Code Block Enhancements Ports
+ *
+ * Module-specific interfaces for code block enhancements
+ */
+
+import type { CodeBlock, CodeBlockOptions } from "../types";
+
+/**
+ * Syntax highlighter interface
+ */
+export interface SyntaxHighlighter {
+	/** Highlight code with language */
+	highlight(code: string, language: string): Promise<string>;
+}
+
+// Re-export types for convenience
+export type { CodeBlock, CodeBlockOptions };

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

@@ -0,0 +1,37 @@
+/**
+ * Code Block Enhancements Types
+ *
+ * Domain types for code block enhancements
+ */
+
+/**
+ * Code block
+ */
+export interface CodeBlock {
+	/** Code content */
+	code: string;
+	/** Language */
+	language?: string;
+	/** Line numbers */
+	lineNumbers?: boolean;
+	/** Highlight lines */
+	highlightLines?: number[];
+	/** File name */
+	filename?: string;
+}
+
+/**
+ * Code block options
+ */
+export interface CodeBlockOptions {
+	/** Enable line numbers */
+	lineNumbers?: boolean;
+	/** Highlight lines */
+	highlightLines?: number[];
+	/** Add copy button */
+	copyButton?: boolean;
+	/** Add filename */
+	filename?: string;
+	/** Theme */
+	theme?: "light" | "dark" | "auto";
+}

package/src/modules/code-execution/application/sandbox-adapter.ts

@@ -0,0 +1,44 @@
+/**
+ * Sandbox adapter implementation.
+ * Provides a safe placeholder for isolated code execution.
+ */
+
+import { configError, pluginError } from "@create-docs/shared/errors";
+import type { ExecutionPort } from "../ports/execution-port";
+import type { CodeExecutionConfig } from "../types/execution";
+
+const SANDBOX_MISSING_ERROR =
+	"Sandbox dependency is not installed. Isolated code execution requires a sandbox package such as vm2 or isolated-vm.";
+
+export const createSandboxAdapter = (): ExecutionPort => ({
+	execute: async (code: string, _config?: unknown) => {
+		const cfg = _config as Partial<CodeExecutionConfig> | undefined;
+
+		if (cfg?.enabled === false) {
+			throw configError("Code execution is disabled", {
+				context: { enabled: false },
+			});
+		}
+
+		if (!cfg?.sandbox) {
+			throw configError("Code execution config requires sandbox: true", {
+				context: { config: cfg },
+				hint: "Enable sandbox in the execution config, or install a sandbox package.",
+			});
+		}
+
+		throw pluginError(SANDBOX_MISSING_ERROR, {
+			context: { codeLength: code.length },
+			hint: "Install an isolated execution sandbox and configure it before running code.",
+		});
+	},
+
+	validate: async (_code: string) => {
+		throw pluginError(
+			"Code validation cannot be performed safely without an isolated sandbox environment.",
+			{
+				hint: "Install a sandbox package and configure it before validating code.",
+			},
+		);
+	},
+});

package/src/modules/code-execution/domain/events/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Domain events for code execution
+ */
+export interface ExecutionStartedEvent {
+	readonly type: "EXECUTION_STARTED";
+	readonly timestamp: number;
+	readonly executionId: string;
+}
+
+export interface ExecutionCompletedEvent {
+	readonly type: "EXECUTION_COMPLETED";
+	readonly timestamp: number;
+	readonly executionId: string;
+	readonly output: string;
+}
+
+export interface ExecutionFailedEvent {
+	readonly type: "EXECUTION_FAILED";
+	readonly timestamp: number;
+	readonly executionId: string;
+	readonly error: string;
+}
+
+export type CodeExecutionDomainEvent =
+	| ExecutionStartedEvent
+	| ExecutionCompletedEvent
+	| ExecutionFailedEvent;
+
+export const createExecutionStartedEvent = (
+	executionId: string,
+	now: number = Date.now(),
+): ExecutionStartedEvent => ({
+	type: "EXECUTION_STARTED",
+	timestamp: now,
+	executionId,
+});
+
+export const createExecutionCompletedEvent = (
+	executionId: string,
+	output: string,
+	now: number = Date.now(),
+): ExecutionCompletedEvent => ({
+	type: "EXECUTION_COMPLETED",
+	timestamp: now,
+	executionId,
+	output,
+});
+
+export const createExecutionFailedEvent = (
+	executionId: string,
+	error: string,
+	now: number = Date.now(),
+): ExecutionFailedEvent => ({
+	type: "EXECUTION_FAILED",
+	timestamp: now,
+	executionId,
+	error,
+});

package/src/modules/code-execution/domain/models/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Domain models for code execution
+ */
+export interface CodeExecution {
+	readonly id: string;
+	readonly language: string;
+	readonly code: string;
+	readonly output?: string;
+	readonly error?: string;
+	readonly status: "pending" | "running" | "completed" | "failed";
+	readonly timestamp: number;
+}
+
+export const createCodeExecution = (
+	id: string,
+	language: string,
+	code: string,
+	options?: {
+		output?: string;
+		error?: string;
+		status?: CodeExecution["status"];
+		timestamp?: number;
+	},
+	now: number = Date.now(),
+): CodeExecution => ({
+	id,
+	language,
+	code,
+	output: options?.output,
+	error: options?.error,
+	status: options?.status ?? "pending",
+	timestamp: options?.timestamp ?? now,
+});

package/src/modules/code-execution/domain/operations/execution-operations.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure code execution 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 {
+	CodeExecutionConfig,
+	ExecutionResult,
+} from "../../types/execution";
+
+export type ExecutionError = {
+	readonly kind: "execution-error";
+	readonly message: string;
+};
+
+/**
+ * Execute code in sandbox.
+ */
+export const executeCode = (
+	_code: string,
+	_config: CodeExecutionConfig,
+): Result<ExecutionResult, ExecutionError> => {
+	try {
+		// This will be implemented via adapter
+		// For now, return a basic result
+		return ok({
+			output: "",
+			error: null,
+			exitCode: 0,
+		});
+	} catch (error) {
+		return err({
+			kind: "execution-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Validate code before execution.
+ */
+export const validateCode = (code: string): boolean => {
+	// Basic validation - check for dangerous operations
+	const dangerousPatterns = [
+		/require\s*\(\s*['"]child_process['"]\s*\)/,
+		/require\s*\(\s*['"]fs['"]\s*\)/,
+		/eval\s*\(/,
+		/Function\s*\(/,
+	];
+
+	for (const pattern of dangerousPatterns) {
+		if (pattern.test(code)) {
+			return false;
+		}
+	}
+
+	return true;
+};

package/src/modules/code-execution/domain/validators/index.ts

@@ -0,0 +1,50 @@
+// Code Execution Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Language Schema
+ */
+export const languageSchema: Type = type("string >= 1");
+
+export type Language = typeof languageSchema.infer;
+
+/**
+ * Code Schema
+ */
+export const codeSchema: Type = type("string >= 1");
+
+export type Code = typeof codeSchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate language using Arktype
+ */
+export const validateLanguage = (language: unknown): Language => {
+	const result = languageSchema(language);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Language must be a non-empty string");
+	}
+	return result as Language;
+};
+
+/**
+ * Validate code using Arktype
+ */
+export const validateCode = (code: unknown): Code => {
+	const result = codeSchema(code);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Code must be a non-empty string");
+	}
+	return result as Code;
+};

package/src/modules/code-execution/index.ts

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

package/src/modules/code-execution/ports/execution-port.ts

@@ -0,0 +1,15 @@
+/**
+ * Port for code execution operations.
+ */
+
+export type ExecutionPort = {
+	/**
+	 * Execute code in sandbox.
+	 */
+	readonly execute: (code: string, config: unknown) => Promise<unknown>;
+
+	/**
+	 * Validate code for safety.
+	 */
+	readonly validate: (code: string) => Promise<boolean>;
+};

package/src/modules/code-execution/types/execution.ts

@@ -0,0 +1,15 @@
+/**
+ * Code execution types for interactive code blocks.
+ */
+
+export type CodeExecutionConfig = {
+	readonly enabled: boolean;
+	readonly timeout: number;
+	readonly sandbox: boolean;
+};
+
+export type ExecutionResult = {
+	readonly output: string;
+	readonly error: string | null;
+	readonly exitCode: number;
+};

package/src/modules/comments/application/giscus-adapter.ts

@@ -0,0 +1,55 @@
+/**
+ * Giscus adapter implementation.
+ * Provides a safe server-side placeholder for Giscus comment integration.
+ */
+
+import { configError, pluginError } from "@create-docs/shared/errors";
+import type { CommentPort } from "../ports/comment-port";
+
+type GiscusConfig = {
+	readonly category?: string;
+	readonly categoryId?: string;
+};
+
+export const createGiscusAdapter = (
+	repo: string,
+	repoId: string,
+): CommentPort => {
+	if (!repo.trim() || !repoId.trim()) {
+		throw configError("Giscus repo and repoId are required", {
+			context: { repo, repoId },
+			hint: "Pass a GitHub repo identifier and giscus repoId.",
+		});
+	}
+
+	return {
+		load: async (pageId: string, config?: unknown) => {
+			const cfg = config as GiscusConfig | undefined;
+
+			if (!cfg?.category && !cfg?.categoryId) {
+				throw configError("Giscus category or categoryId is required", {
+					context: { repo, repoId, pageId },
+					hint: "Set category and categoryId in the comment config.",
+				});
+			}
+
+			throw pluginError(
+				"Giscus comments require the @giscus/react client component and a GitHub Discussions repository.",
+				{
+					context: { repo, repoId, pageId },
+					hint: "Install and configure @giscus/react, or switch to a different comment provider.",
+				},
+			);
+		},
+
+		submit: async (_comment: unknown, _config?: unknown) => {
+			throw pluginError(
+				"Giscus submission requires the @giscus/react client component.",
+				{
+					context: { repo, repoId },
+					hint: "Install and configure @giscus/react, or switch to a different comment provider.",
+				},
+			);
+		},
+	};
+};

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

@@ -0,0 +1,55 @@
+/**
+ * Domain events for comments
+ */
+export interface CommentAddedEvent {
+	readonly type: "COMMENT_ADDED";
+	readonly timestamp: number;
+	readonly commentId: string;
+	readonly author: string;
+}
+
+export interface CommentUpdatedEvent {
+	readonly type: "COMMENT_UPDATED";
+	readonly timestamp: number;
+	readonly commentId: string;
+}
+
+export interface CommentDeletedEvent {
+	readonly type: "COMMENT_DELETED";
+	readonly timestamp: number;
+	readonly commentId: string;
+}
+
+export type CommentsDomainEvent =
+	| CommentAddedEvent
+	| CommentUpdatedEvent
+	| CommentDeletedEvent;
+
+export const createCommentAddedEvent = (
+	commentId: string,
+	author: string,
+	now: number = Date.now(),
+): CommentAddedEvent => ({
+	type: "COMMENT_ADDED",
+	timestamp: now,
+	commentId,
+	author,
+});
+
+export const createCommentUpdatedEvent = (
+	commentId: string,
+	now: number = Date.now(),
+): CommentUpdatedEvent => ({
+	type: "COMMENT_UPDATED",
+	timestamp: now,
+	commentId,
+});
+
+export const createCommentDeletedEvent = (
+	commentId: string,
+	now: number = Date.now(),
+): CommentDeletedEvent => ({
+	type: "COMMENT_DELETED",
+	timestamp: now,
+	commentId,
+});

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

@@ -0,0 +1,30 @@
+/**
+ * Domain models for comments
+ */
+export interface Comment {
+	readonly id: string;
+	readonly author: string;
+	readonly content: string;
+	readonly timestamp: number;
+	readonly parentId?: string;
+	readonly replies?: readonly Comment[];
+}
+
+export const createComment = (
+	id: string,
+	author: string,
+	content: string,
+	options?: {
+		parentId?: string;
+		replies?: readonly Comment[];
+		timestamp?: number;
+	},
+	now: number = Date.now(),
+): Comment => ({
+	id,
+	author,
+	content,
+	parentId: options?.parentId,
+	replies: options?.replies,
+	timestamp: options?.timestamp ?? now,
+});

package/src/modules/comments/domain/operations/comment-operations.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure comment 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 { Comment, CommentConfig } from "../../types/comments";
+
+export type CommentError = {
+	readonly kind: "comment-error";
+	readonly message: string;
+};
+
+/**
+ * Validate comment content.
+ */
+export const validateComment = (content: string): boolean => {
+	if (content.length === 0) return false;
+	if (content.length > 5000) return false;
+	return true;
+};
+
+/**
+ * Format comment for display.
+ */
+export const formatComment = (comment: Comment): string => {
+	return comment.content;
+};
+
+/**
+ * Get comment widget config.
+ */
+export const getCommentWidgetConfig = (
+	_config: CommentConfig,
+): Result<unknown, CommentError> => {
+	try {
+		// This will be implemented via adapter
+		return ok({});
+	} catch (error) {
+		return err({
+			kind: "comment-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};

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

@@ -0,0 +1,50 @@
+// Comments Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Author Schema
+ */
+export const authorSchema: Type = type("string >= 1");
+
+export type Author = typeof authorSchema.infer;
+
+/**
+ * Content Schema
+ */
+export const contentSchema: Type = type("string >= 1");
+
+export type Content = typeof contentSchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate author using Arktype
+ */
+export const validateAuthor = (author: unknown): Author => {
+	const result = authorSchema(author);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Author must be a non-empty string");
+	}
+	return result as Author;
+};
+
+/**
+ * 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 non-empty string");
+	}
+	return result as Content;
+};

package/src/modules/comments/index.ts

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