@wrikka/create-docs 0.1.0

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

@@ -0,0 +1,80 @@
+/**
+ * Live Editor Types
+ *
+ * Domain types for live editor with Git integration
+ */
+
+/**
+ * Editor mode
+ */
+export type EditorMode = "preview" | "edit" | "split";
+
+/**
+ * File content
+ */
+export interface FileContent {
+	/** File path */
+	path: string;
+	/** File content */
+	content: string;
+	/** Language (for syntax highlighting) */
+	language?: string;
+	/** Last modified timestamp */
+	mtimeMs?: number;
+}
+
+/**
+ * Git status
+ */
+export interface GitStatus {
+	/** Current branch */
+	branch: string;
+	/** Has uncommitted changes */
+	hasChanges: boolean;
+	/** Untracked files */
+	untracked: string[];
+	/** Modified files */
+	modified: string[];
+	/** Staged files */
+	staged: string[];
+}
+
+/**
+ * Commit options
+ */
+export interface CommitOptions {
+	/** Commit message */
+	message: string;
+	/** Author name */
+	author?: string;
+	/** Author email */
+	email?: string;
+}
+
+/**
+ * Push options
+ */
+export interface PushOptions {
+	/** Remote name (default: origin) */
+	remote?: string;
+	/** Branch name (default: current branch) */
+	branch?: string;
+	/** Force push */
+	force?: boolean;
+}
+
+/**
+ * Editor state
+ */
+export interface EditorState {
+	/** Current mode */
+	mode: EditorMode;
+	/** Current file */
+	currentFile: FileContent | null;
+	/** Git status */
+	gitStatus: GitStatus | null;
+	/** Is loading */
+	loading: boolean;
+	/** Error message */
+	error?: string;
+}

package/src/modules/live-preview/application/vite-preview-adapter.ts

@@ -0,0 +1,20 @@
+/**
+ * Vite preview adapter implementation.
+ * Provides WebSocket-based live preview integration.
+ */
+
+import type { PreviewPort } from "../ports/preview-port";
+
+export const createVitePreviewAdapter = (): PreviewPort => ({
+	start: async (_config?: unknown) => {
+		// This will integrate with Vite HMR
+	},
+
+	stop: async () => {
+		// This will stop the preview server
+	},
+
+	update: async (_content: string) => {
+		// This will send content update via WebSocket
+	},
+});

package/src/modules/live-preview/domain/operations/preview-operations.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure live preview 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 { PreviewConfig, PreviewState } from "../../types/preview";
+
+export type PreviewError = {
+	readonly kind: "preview-error";
+	readonly message: string;
+};
+
+/**
+ * Update preview state with new content.
+ */
+export const updatePreview = (
+	state: PreviewState,
+	content: string,
+): Result<PreviewState, PreviewError> => {
+	try {
+		return ok({
+			...state,
+			content,
+			error: null,
+		});
+	} catch (error) {
+		return err({
+			kind: "preview-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Set preview error.
+ */
+export const setPreviewError = (
+	state: PreviewState,
+	error: Error,
+): PreviewState => ({
+	...state,
+	error,
+});
+
+/**
+ * Toggle preview mode.
+ */
+export const togglePreview = (
+	state: PreviewState,
+	_config: PreviewConfig,
+): PreviewState => ({
+	...state,
+	isPreviewing: !state.isPreviewing,
+});

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

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

package/src/modules/live-preview/ports/preview-port.ts

@@ -0,0 +1,20 @@
+/**
+ * Port for live preview operations.
+ */
+
+export type PreviewPort = {
+	/**
+	 * Start preview server.
+	 */
+	readonly start: (config: unknown) => Promise<void>;
+
+	/**
+	 * Stop preview server.
+	 */
+	readonly stop: () => Promise<void>;
+
+	/**
+	 * Send content update via WebSocket.
+	 */
+	readonly update: (content: string) => Promise<void>;
+};

package/src/modules/live-preview/types/preview.ts

@@ -0,0 +1,16 @@
+/**
+ * Live preview types for real-time markdown preview.
+ */
+
+export type PreviewState = {
+	readonly isPreviewing: boolean;
+	readonly currentPath: string;
+	readonly content: string;
+	readonly error: Error | null;
+};
+
+export type PreviewConfig = {
+	readonly enabled: boolean;
+	readonly splitView: boolean;
+	readonly syncScroll: boolean;
+};

package/src/modules/mdx/application/mdx-js-adapter.ts

@@ -0,0 +1,38 @@
+/**
+ * @mdx-js/mdx adapter implementation.
+ * Provides MDX parsing and compilation.
+ */
+
+import { pluginError } from "@create-docs/shared/errors";
+import { compile } from "@mdx-js/mdx";
+import type { MdxParserPort } from "../ports/mdx-parser-port";
+
+export const createMdxJsAdapter = (): MdxParserPort => ({
+	parse: async (raw: string, options?: unknown) => {
+		try {
+			const result = await compile(raw, {
+				...(options as Record<string, unknown>),
+				outputFormat: "function-body",
+			});
+			return result.toString();
+		} catch (error) {
+			throw pluginError("MDX parsing failed", {
+				context: { options, error: String(error) },
+			});
+		}
+	},
+
+	compile: async (raw: string, options?: unknown) => {
+		try {
+			const result = await compile(raw, {
+				...(options as Record<string, unknown>),
+				outputFormat: "function-body",
+			});
+			return result.toString();
+		} catch (error) {
+			throw pluginError("MDX compilation failed", {
+				context: { options, error: String(error) },
+			});
+		}
+	},
+});

package/src/modules/mdx/domain/operations/parse-mdx.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure MDX parser 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 { MdxOptions } from "../../types/mdx";
+
+export type MdxParseError = {
+	readonly kind: "mdx-parse-error";
+	readonly message: string;
+	readonly line?: number;
+	readonly column?: number;
+};
+
+/**
+ * Parse MDX string to component code.
+ * Uses @mdx-js/mdx adapter.
+ */
+export const parseMdx = (
+	raw: string,
+	_options: MdxOptions = {},
+): Result<string, MdxParseError> => {
+	try {
+		// This will be implemented via adapter
+		// For now, return the raw content as-is
+		return ok(raw);
+	} catch (error) {
+		return err({
+			kind: "mdx-parse-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Determine if a file is an MDX file.
+ */
+export const isMdxFile = (fileName: string): boolean =>
+	fileName.endsWith(".mdx") ||
+	fileName.endsWith(".mdx.tsx") ||
+	fileName.endsWith(".mdx.jsx");

package/src/modules/mdx/index.ts

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

package/src/modules/mdx/ports/mdx-parser-port.ts

@@ -0,0 +1,15 @@
+/**
+ * Port for MDX parsing operations.
+ */
+
+export type MdxParserPort = {
+	/**
+	 * Parse MDX string to component code.
+	 */
+	readonly parse: (raw: string, options?: unknown) => Promise<string>;
+
+	/**
+	 * Compile MDX to JavaScript.
+	 */
+	readonly compile: (raw: string, options?: unknown) => Promise<string>;
+};

package/src/modules/mdx/types/mdx.ts

@@ -0,0 +1,14 @@
+/**
+ * MDX types for MDX support.
+ */
+
+export type MdxComponent = {
+	readonly name: string;
+	readonly source: string;
+};
+
+export type MdxOptions = {
+	readonly components?: Readonly<Record<string, MdxComponent>>;
+	readonly remarkPlugins?: readonly unknown[];
+	readonly rehypePlugins?: readonly unknown[];
+};

package/src/modules/navigation/application/usecases/buildNav.ts

@@ -0,0 +1,15 @@
+/**
+ * Use case: select or fallback to the navigation structure.
+ * Pure: depends only on config input.
+ */
+
+import type { AppError } from "@create-docs/shared/errors";
+import { ok, type Result } from "@create-docs/shared/types/result";
+import { sortNavSections } from "../../domain/operations/sort";
+import type { NavSection } from "../../types";
+
+export type BuildNav = (
+	sections: readonly NavSection[],
+) => Result<readonly NavSection[], AppError>;
+
+export const buildNav: BuildNav = (sections) => ok(sortNavSections(sections));

package/src/modules/navigation/application/usecases/buildSidebar.ts

@@ -0,0 +1,45 @@
+/**
+ * Use case: build the sidebar from either a user-defined config or
+ * the scanned docs directory.
+ */
+
+import type { DocFile, DocPage } from "@create-docs/modules/content";
+import type { AppError } from "@create-docs/shared/errors";
+import type { Result } from "@create-docs/shared/types/result";
+import { ok } from "@create-docs/shared/types/result";
+import {
+	groupDocsByFolder,
+	type SidebarSource,
+} from "../../domain/operations/group";
+import {
+	sortSidebarGroups,
+	sortSidebarItems,
+} from "../../domain/operations/sort";
+import type { SidebarGroup } from "../../types";
+
+export interface BuildSidebarInput {
+	/** Explicit sidebar from config (overrides auto-generation). */
+	readonly configured?: readonly SidebarGroup[];
+	/** All scanned doc files (used when no explicit sidebar). */
+	readonly docs?: readonly DocFile[];
+	/** All built doc pages (used as a richer source when available). */
+	readonly pages?: readonly DocPage[];
+}
+
+export type BuildSidebar = (
+	input: BuildSidebarInput,
+) => Result<readonly SidebarGroup[], AppError>;
+
+export const buildSidebar: BuildSidebar = ({ configured, docs, pages }) => {
+	if (configured && configured.length > 0) {
+		const sorted = configured.map((g) => ({
+			...g,
+			items: sortSidebarItems(g.items),
+		}));
+		return ok(sortSidebarGroups(sorted));
+	}
+	const sources: readonly SidebarSource[] =
+		pages !== undefined && pages.length > 0 ? pages : (docs ?? []);
+	if (sources.length === 0) return ok([]);
+	return ok(sortSidebarGroups(groupDocsByFolder(sources)));
+};

package/src/modules/navigation/application/usecases/index.ts

@@ -0,0 +1,2 @@
+export { buildNav } from "./buildNav";
+export { buildSidebar } from "./buildSidebar";

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

@@ -0,0 +1,30 @@
+/**
+ * Domain events for the navigation module.
+ * Pure event types — no handlers.
+ */
+import type { SidebarGroup } from "../../types";
+
+export type NavigationEvent =
+	| { readonly type: "nav.generated"; readonly groupsCount: number }
+	| {
+			readonly type: "nav.rebuilt";
+			readonly reason: "config_changed" | "content_changed" | "manual";
+	  }
+	| { readonly type: "sidebar.group_built"; readonly group: SidebarGroup };
+
+export const navGenerated = (groupsCount: number): NavigationEvent => ({
+	type: "nav.generated",
+	groupsCount,
+});
+
+export const navRebuilt = (
+	reason: "config_changed" | "content_changed" | "manual",
+): NavigationEvent => ({
+	type: "nav.rebuilt",
+	reason,
+});
+
+export const sidebarGroupBuilt = (group: SidebarGroup): NavigationEvent => ({
+	type: "sidebar.group_built",
+	group,
+});

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

@@ -0,0 +1,7 @@
+export type {
+	NavItem,
+	NavSection,
+	Sidebar,
+	SidebarGroup,
+	SidebarItem,
+} from "../../types";

package/src/modules/navigation/domain/operations/group.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure operations for generating and formatting navigation structures.
+ * No I/O. No mutation of inputs.
+ */
+
+import type { DocFile, DocPage } from "@create-docs/modules/content";
+import { SIDEBAR_DEFAULT_GROUP_TITLE } from "@create-docs/shared/constants";
+import { capitalize, titleCase } from "@create-docs/shared/utils/string";
+import type { SidebarGroup, SidebarItem } from "../../types";
+import { groupBy, sortBy } from "../shared/utils/array";
+
+export interface GroupInput {
+	readonly slug: string;
+	readonly title: string;
+	readonly order: number;
+	readonly group?: string;
+	readonly badge?: string;
+	readonly badgeVariant?: SidebarItem["badgeVariant"];
+}
+
+/** Structural subset needed to derive a sidebar item. Both DocFile and DocPage satisfy it. */
+export interface SidebarSource {
+	readonly slug: DocFile["slug"] | DocPage["slug"];
+	readonly group?: string;
+	readonly order: number;
+	readonly frontmatter: DocFile["frontmatter"];
+}
+
+/** Format a folder name into a human-readable group title. */
+export const formatGroupTitle = (name: string): string => {
+	if (name === "root") return SIDEBAR_DEFAULT_GROUP_TITLE;
+	return titleCase(name);
+};
+
+/** Group doc files by their first path segment, sorting each by `order`. */
+export const groupDocsByFolder = (
+	docs: readonly SidebarSource[],
+): readonly SidebarGroup[] => {
+	const grouped = groupBy(docs, (d) => d.group ?? "root");
+	const groups: SidebarGroup[] = [];
+	for (const [key, items] of Object.entries(grouped)) {
+		const sorted = sortBy(items, (i) => i.order);
+		groups.push({
+			title: formatGroupTitle(key),
+			items: sorted.map(toSidebarItem),
+		});
+	}
+	return groups.sort((a, b) => a.title.localeCompare(b.title));
+};
+
+const toSidebarItem = (doc: SidebarSource): SidebarItem => {
+	const fm = doc.frontmatter as Record<string, unknown>;
+	const item: SidebarItem = {
+		title: deriveTitle(doc),
+		slug: typeof doc.slug === "string" ? doc.slug : String(doc.slug),
+	};
+	if (typeof fm.badge === "string") {
+		const withBadge: SidebarItem = { ...item, badge: fm.badge };
+		if (isBadgeVariant(fm.badgeVariant)) {
+			return { ...withBadge, badgeVariant: fm.badgeVariant };
+		}
+		return withBadge;
+	}
+	return item;
+};
+
+const deriveTitle = (doc: SidebarSource): string => {
+	const fm = doc.frontmatter as Record<string, unknown>;
+	if (typeof fm.title === "string" && fm.title.trim().length > 0)
+		return fm.title;
+	const slugStr = typeof doc.slug === "string" ? doc.slug : String(doc.slug);
+	const last = slugStr.split("/").pop();
+	return last ? capitalize(last) : slugStr;
+};
+
+const isBadgeVariant = (
+	v: unknown,
+): v is NonNullable<SidebarItem["badgeVariant"]> =>
+	v === "default" || v === "success" || v === "warning" || v === "danger";

package/src/modules/navigation/domain/operations/index.ts

@@ -0,0 +1,10 @@
+export {
+	formatGroupTitle,
+	groupDocsByFolder,
+} from "./group";
+export {
+	sortNavItems,
+	sortNavSections,
+	sortSidebarGroups,
+	sortSidebarItems,
+} from "./sort";

package/src/modules/navigation/domain/operations/sort.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure operations for sorting/ordering nav items.
+ */
+
+import type {
+	NavItem,
+	NavSection,
+	SidebarGroup,
+	SidebarItem,
+} from "../../types";
+import { sortByString } from "../shared/utils/array";
+
+export const sortNavSections = (
+	sections: readonly NavSection[],
+): readonly NavSection[] =>
+	[...sections].sort((a, b) => a.title.localeCompare(b.title));
+
+export const sortNavItems = (items: readonly NavItem[]): readonly NavItem[] =>
+	sortByString(items, (i) => i.label);
+
+export const sortSidebarGroups = (
+	groups: readonly SidebarGroup[],
+): readonly SidebarGroup[] => sortByString(groups, (g) => g.title);
+
+export const sortSidebarItems = (
+	items: readonly SidebarItem[],
+): readonly SidebarItem[] => sortByString(items, (i) => i.title);

package/src/modules/navigation/domain/shared/utils/array.ts

@@ -0,0 +1,39 @@
+/**
+ * Pure array helpers used by navigation domain operations.
+ */
+
+export const sortBy = <T, K extends number | string>(
+	items: readonly T[],
+	keyFn: (item: T) => K,
+): T[] => {
+	return [...items].sort((a, b) => {
+		const ka = keyFn(a);
+		const kb = keyFn(b);
+		if (typeof ka === "number" && typeof kb === "number") {
+			return ka - kb;
+		}
+		return String(ka).localeCompare(String(kb));
+	});
+};
+
+export const sortByString = <T>(
+	items: readonly T[],
+	keyFn: (item: T) => string,
+): T[] => {
+	return [...items].sort((a, b) => keyFn(a).localeCompare(keyFn(b)));
+};
+
+export const groupBy = <T, K extends string | number>(
+	items: readonly T[],
+	keyFn: (item: T) => K,
+): Record<string, T[]> => {
+	const result: Record<string, T[]> = {};
+	for (const item of items) {
+		const key = String(keyFn(item));
+		if (!result[key]) {
+			result[key] = [];
+		}
+		result[key].push(item);
+	}
+	return result;
+};

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

@@ -0,0 +1,88 @@
+// Navigation Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { validationError } from "@create-docs/shared/errors";
+import { err, ok, type Result } from "@create-docs/shared/types/result";
+import { type Type, type } from "arktype";
+import type {
+	NavItem,
+	NavSection,
+	SidebarGroup,
+	SidebarItem,
+} from "../../types";
+
+/**
+ * Nav Item Schema
+ */
+export const navItemSchema: Type = type({
+	label: "string >= 1",
+	"href?": "string >= 1",
+});
+
+/**
+ * Nav Section Schema
+ */
+export const navSectionSchema: Type = type({
+	title: "string >= 1",
+	items: "unknown[]",
+});
+
+/**
+ * Sidebar Item Schema
+ */
+export const sidebarItemSchema: Type = type({
+	title: "string >= 1",
+	slug: "string >= 1",
+});
+
+/**
+ * Sidebar Group Schema
+ */
+export const sidebarGroupSchema: Type = type({
+	title: "string >= 1",
+	items: "unknown[]",
+});
+
+export const validateNavItem = (
+	i: NavItem,
+	path: string,
+): Result<NavItem, ReturnType<typeof validationError>> => {
+	const result = navItemSchema(i);
+	if (result instanceof type.errors) {
+		return err(validationError(result.summary, { path }));
+	}
+	return ok(i);
+};
+
+export const validateNavSection = (
+	s: NavSection,
+	path: string,
+): Result<NavSection, ReturnType<typeof validationError>> => {
+	const result = navSectionSchema(s);
+	if (result instanceof type.errors) {
+		return err(validationError(result.summary, { path }));
+	}
+	return ok(s);
+};
+
+export const validateSidebarItem = (
+	i: SidebarItem,
+	path: string,
+): Result<SidebarItem, ReturnType<typeof validationError>> => {
+	const result = sidebarItemSchema(i);
+	if (result instanceof type.errors) {
+		return err(validationError(result.summary, { path }));
+	}
+	return ok(i);
+};
+
+export const validateSidebarGroup = (
+	g: SidebarGroup,
+	path: string,
+): Result<SidebarGroup, ReturnType<typeof validationError>> => {
+	const result = sidebarGroupSchema(g);
+	if (result instanceof type.errors) {
+		return err(validationError(result.summary, { path }));
+	}
+	return ok(g);
+};