@wrikka/create-docs 0.1.0

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

@@ -0,0 +1,50 @@
+// Workflow Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Step Name Schema
+ */
+export const stepNameSchema: Type = type("string >= 1");
+
+export type StepName = typeof stepNameSchema.infer;
+
+/**
+ * Workflow Name Schema
+ */
+export const workflowNameSchema: Type = type("string >= 1");
+
+export type WorkflowName = typeof workflowNameSchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate step name using Arktype
+ */
+export const validateStepName = (name: unknown): StepName => {
+	const result = stepNameSchema(name);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Step name must be a non-empty string");
+	}
+	return result as StepName;
+};
+
+/**
+ * Validate workflow name using Arktype
+ */
+export const validateWorkflowName = (name: unknown): WorkflowName => {
+	const result = workflowNameSchema(name);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Workflow name must be a non-empty string");
+	}
+	return result as WorkflowName;
+};

package/src/modules/yaml-parser/application/js-yaml-adapter.ts

@@ -0,0 +1,34 @@
+/**
+ * js-yaml adapter implementation.
+ * Provides full YAML 1.2 support with safe mode.
+ */
+
+import { ioError, parseError } from "@create-docs/shared/errors";
+import yaml from "js-yaml";
+import type { YamlParserPort } from "../ports/yaml-parser-port";
+
+export const createJsYamlAdapter = (): YamlParserPort => ({
+	parse: async (raw: string) => {
+		try {
+			return yaml.load(raw, {
+				schema: yaml.DEFAULT_SCHEMA,
+				// Safe mode - no eval, no function scalars
+			});
+		} catch (error) {
+			throw parseError("<input>", "YAML parsing failed", error);
+		}
+	},
+
+	stringify: async (value: unknown) => {
+		try {
+			return yaml.dump(value, {
+				schema: yaml.DEFAULT_SCHEMA,
+				indent: 2,
+				lineWidth: -1,
+				noRefs: true,
+			});
+		} catch (error) {
+			throw ioError("<output>", "YAML stringification failed", error);
+		}
+	},
+});

package/src/modules/yaml-parser/domain/operations/parse-yaml.ts

@@ -0,0 +1,58 @@
+/**
+ * Pure YAML 1.2 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 { dump, JSON_SCHEMA, load, YAMLException } from "js-yaml";
+
+export type YamlParseError = {
+	readonly kind: "yaml-parse-error";
+	readonly message: string;
+	readonly line?: number;
+	readonly column?: number;
+};
+
+/**
+ * Parse YAML string with safe YAML 1.2 schema.
+ */
+export const parseYaml = (raw: string): Result<unknown, YamlParseError> => {
+	try {
+		const value = load(raw, { schema: JSON_SCHEMA });
+		return ok(value);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Unknown error";
+		const line = error instanceof YAMLException ? error.mark?.line : undefined;
+		const column =
+			error instanceof YAMLException ? error.mark?.column : undefined;
+		return err({
+			kind: "yaml-parse-error",
+			message,
+			line,
+			column,
+		});
+	}
+};
+
+/**
+ * Stringify object to YAML.
+ */
+export const stringifyYaml = (
+	value: unknown,
+): Result<string, YamlParseError> => {
+	try {
+		const result = dump(value, {
+			schema: JSON_SCHEMA,
+			indent: 2,
+			lineWidth: -1,
+			noRefs: true,
+		});
+		return ok(result);
+	} catch (error) {
+		return err({
+			kind: "yaml-parse-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};

package/src/modules/yaml-parser/index.ts

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

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

@@ -0,0 +1,18 @@
+/**
+ * Port for YAML parsing operations.
+ * Defines the interface for YAML adapter implementations.
+ */
+
+export type YamlParserPort = {
+	/**
+	 * Parse YAML string with full YAML 1.2 support.
+	 * Safe mode enabled - no eval, no function scalars.
+	 */
+	readonly parse: (raw: string) => Promise<unknown>;
+
+	/**
+	 * Stringify object to YAML with full YAML 1.2 support.
+	 * Safe mode enabled - no eval, no function scalars.
+	 */
+	readonly stringify: (value: unknown) => Promise<string>;
+};

package/src/navigation/index.ts

@@ -0,0 +1,9 @@
+export type NavItem = unknown;
+export type NavSection = unknown;
+export type Sidebar = unknown;
+export type SidebarGroup = unknown;
+export type SidebarItem = unknown;
+export const buildNav = () => null;
+export const buildSidebar = () => null;
+export const formatGroupTitle = () => null;
+export const groupDocsByFolder = () => null;

package/src/plugin/index.ts

@@ -0,0 +1,4 @@
+export type VirtualModuleSet = unknown;
+export const buildVirtualModules = () => null;
+export const isMarkdownPath = () => null;
+export const isVirtualDocsModule = () => null;

package/src/presentation/index.ts

@@ -0,0 +1 @@
+export * from "./vite-plugin";

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

@@ -0,0 +1,22 @@
+/**
+ * Live Editor Presentation
+ *
+ * Presentation layer for live editor with Git integration
+ */
+
+export {
+	createLiveEditorState,
+	type EditorMode,
+	type LiveEditorOptions,
+	type LiveEditorState,
+	liveEditorAttachEventListeners,
+	liveEditorDestroy,
+	liveEditorInitEditor,
+	liveEditorRender,
+	liveEditorSetMode,
+	liveEditorUpdateGitStatus,
+} from "./live-editor-component";
+export {
+	LIVE_EDITOR_MODULE_ID,
+	liveEditorVirtualModuleCode,
+} from "./virtual-module";

package/src/presentation/live-editor/live-editor-component.ts

@@ -0,0 +1,219 @@
+/**
+ * Live Editor Component (Vanilla JS)
+ *
+ * Live editor with split view (preview/edit) using CodeMirror
+ */
+
+import { basicSetup } from "@codemirror/basic-setup";
+import { markdown } from "@codemirror/lang-markdown";
+import { EditorState } from "@codemirror/state";
+import { EditorView } from "@codemirror/view";
+import type { CommitOptions, GitStatus } from "../../modules/live-editor/types";
+
+export interface LiveEditorOptions {
+	/** Container element */
+	container: HTMLElement;
+	/** Initial content */
+	initialContent: string;
+	/** Git status */
+	gitStatus?: GitStatus;
+	/** On save callback */
+	onSave?: (content: string) => Promise<void>;
+	/** On commit callback */
+	onCommit?: (options: CommitOptions) => Promise<void>;
+	/** On push callback */
+	onPush?: () => Promise<void>;
+}
+
+export type EditorMode = "preview" | "edit" | "split";
+
+// Live editor state
+export interface LiveEditorState {
+	readonly container: HTMLElement;
+	readonly editorView: EditorView | null;
+	readonly previewElement: HTMLElement;
+	readonly content: string;
+	readonly gitStatus?: GitStatus;
+	readonly onSave?: (content: string) => Promise<void>;
+	readonly onCommit?: (options: CommitOptions) => Promise<void>;
+	readonly onPush?: () => Promise<void>;
+	readonly mode: EditorMode;
+}
+
+export const createLiveEditorState = (
+	options: LiveEditorOptions,
+): LiveEditorState => ({
+	container: options.container,
+	editorView: null,
+	previewElement: document.createElement("div"),
+	content: options.initialContent,
+	gitStatus: options.gitStatus,
+	onSave: options.onSave,
+	onCommit: options.onCommit,
+	onPush: options.onPush,
+	mode: "split",
+});
+
+export const liveEditorRender = (state: LiveEditorState): LiveEditorState => {
+	state.container.innerHTML = "";
+
+	// Toolbar
+	const toolbar = document.createElement("div");
+	toolbar.className = "live-editor-toolbar";
+	toolbar.innerHTML = `
+		<div class="toolbar-left">
+			<button data-mode="preview" class="${state.mode === "preview" ? "active" : ""}">Preview</button>
+			<button data-mode="edit" class="${state.mode === "edit" ? "active" : ""}">Edit</button>
+			<button data-mode="split" class="${state.mode === "split" ? "active" : ""}">Split</button>
+		</div>
+		<div class="toolbar-right">
+			${state.gitStatus ? `<span class="git-status">${state.gitStatus.branch} ${state.gitStatus.hasChanges ? "(modified)" : ""}</span>` : ""}
+			<button class="save-btn">Save</button>
+			<button class="commit-btn">Commit</button>
+			<button class="push-btn">Push</button>
+		</div>
+	`;
+
+	// Commit input
+	const commitInput = document.createElement("div");
+	commitInput.className = "commit-input";
+	commitInput.innerHTML = `
+		<input type="text" placeholder="Commit message..." class="commit-message-input">
+	`;
+
+	// Content area
+	const contentArea = document.createElement("div");
+	contentArea.className = `live-editor-content mode-${state.mode}`;
+
+	// Editor pane
+	const editorPane = document.createElement("div");
+	editorPane.className = "editor-pane";
+
+	// Preview pane
+	const previewElement = document.createElement("div");
+	previewElement.className = "preview-pane";
+	previewElement.innerHTML = state.content;
+
+	contentArea.appendChild(editorPane);
+	contentArea.appendChild(previewElement);
+
+	state.container.appendChild(toolbar);
+	state.container.appendChild(commitInput);
+	state.container.appendChild(contentArea);
+
+	// Initialize CodeMirror
+	const editorView = liveEditorInitEditor(state, editorPane);
+
+	// Event listeners
+	liveEditorAttachEventListeners(state, toolbar, commitInput);
+
+	return {
+		...state,
+		editorView,
+		previewElement,
+	};
+};
+
+export const liveEditorInitEditor = (
+	state: LiveEditorState,
+	container: HTMLElement,
+): EditorView => {
+	const editorState = EditorState.create({
+		doc: state.content,
+		extensions: [basicSetup, markdown()],
+	});
+
+	const editorView = new EditorView({
+		state: editorState,
+		parent: container,
+	});
+
+	editorView.contentDOM.addEventListener("input", () => {
+		// Content update would be handled by state update
+	});
+
+	return editorView;
+};
+
+export const liveEditorAttachEventListeners = (
+	state: LiveEditorState,
+	toolbar: HTMLElement,
+	commitInput: HTMLElement,
+): void => {
+	// Mode buttons
+	toolbar.querySelectorAll("[data-mode]").forEach((btn) => {
+		btn.addEventListener("click", (e) => {
+			void ((e.target as HTMLElement).dataset.mode as EditorMode);
+			// Mode change would be handled by state update
+		});
+	});
+
+	// Save button
+	toolbar.querySelector(".save-btn")?.addEventListener("click", async () => {
+		if (state.onSave) {
+			await state.onSave(state.content);
+		}
+	});
+
+	// Commit button
+	toolbar.querySelector(".commit-btn")?.addEventListener("click", async () => {
+		const input = commitInput.querySelector(
+			".commit-message-input",
+		) as HTMLInputElement;
+		const message = input.value;
+		if (state.onCommit && message) {
+			await state.onCommit({ message });
+			input.value = "";
+		}
+	});
+
+	// Push button
+	toolbar.querySelector(".push-btn")?.addEventListener("click", async () => {
+		if (state.onPush) {
+			await state.onPush();
+		}
+	});
+};
+
+export const liveEditorSetMode = (
+	state: LiveEditorState,
+	mode: EditorMode,
+): LiveEditorState => {
+	const contentArea = state.container.querySelector(
+		".live-editor-content",
+	) as HTMLElement;
+	contentArea.className = `live-editor-content mode-${mode}`;
+
+	// Update active button
+	state.container.querySelectorAll("[data-mode]").forEach((btn) => {
+		const btnMode = (btn as HTMLElement).dataset.mode;
+		if (btnMode) {
+			(btn as HTMLElement).classList.toggle("active", btnMode === mode);
+		}
+	});
+
+	return {
+		...state,
+		mode,
+	};
+};
+
+export const liveEditorUpdateGitStatus = (
+	state: LiveEditorState,
+	status: GitStatus,
+): LiveEditorState => {
+	const statusEl = state.container.querySelector(".git-status");
+	if (statusEl) {
+		statusEl.textContent = `${status.branch} ${status.hasChanges ? "(modified)" : ""}`;
+	}
+
+	return {
+		...state,
+		gitStatus: status,
+	};
+};
+
+export const liveEditorDestroy = (state: LiveEditorState): void => {
+	state.editorView?.destroy();
+	state.container.innerHTML = "";
+};

package/src/presentation/live-editor/virtual-module.ts

@@ -0,0 +1,16 @@
+/**
+ * Live Editor Virtual Module
+ *
+ * Virtual module that provides live editor UI components
+ */
+
+export const LIVE_EDITOR_MODULE_ID = "virtual:create-docs-live-editor";
+
+export const liveEditorVirtualModuleCode = `
+import { loader } from '@monaco-editor/react';
+import * as monaco from 'monaco-editor';
+
+loader.config({ monaco });
+
+export { default } from './live-editor-component';
+`;

package/src/presentation/solid/CodeBlock.tsx

@@ -0,0 +1,120 @@
+/**
+ * Solid CodeBlock Component
+ *
+ * Code block component with syntax highlighting and copy functionality
+ */
+
+import { createSignal, For, onMount, Show } from "solid-js";
+import type { CodeBlockOptions } from "../../modules/code-block-enhancements";
+
+export interface CodeBlockProps extends CodeBlockOptions {
+	/** Code content */
+	code: string;
+	/** Language */
+	language?: string;
+}
+
+export const CodeBlock = (props: CodeBlockProps) => {
+	const [copied, setCopied] = createSignal(false);
+	const [highlightedCode, setHighlightedCode] = createSignal("");
+
+	const handleCopy = async () => {
+		try {
+			await navigator.clipboard.writeText(props.code);
+			setCopied(true);
+			setTimeout(() => setCopied(false), 2000);
+		} catch (err) {
+			console.error("Failed to copy code:", err);
+		}
+	};
+
+	onMount(() => {
+		// Lightweight syntax highlighter. For full language support add Shiki.
+		let highlighted = props.code
+			.replace(/&/g, "&")
+			.replace(/</g, "&lt;")
+			.replace(/>/g, "&gt;");
+
+		// Simple keyword highlighting for common languages
+		if (props.language === "typescript" || props.language === "ts") {
+			highlighted = highlighted
+				.replace(
+					/\b(const|let|var|function|return|if|else|for|while|import|export|from|interface|type|class|extends|implements)\b/g,
+					'<span class="keyword">$1</span>',
+				)
+				.replace(
+					/\b(string|number|boolean|void|any|never)\b/g,
+					'<span class="type">$1</span>',
+				);
+		} else if (props.language === "javascript" || props.language === "js") {
+			highlighted = highlighted.replace(
+				/\b(const|let|var|function|return|if|else|for|while|import|export|from|class|extends)\b/g,
+				'<span class="keyword">$1</span>',
+			);
+		} else if (props.language === "json") {
+			highlighted = highlighted
+				.replace(/"([^"\\]*)"/g, '<span class="string">"$1"</span>')
+				.replace(/\b(true|false|null)\b/g, '<span class="keyword">$1</span>');
+		} else if (props.language === "bash" || props.language === "shell") {
+			highlighted = highlighted.replace(
+				/(^|\s)(bun|npm|pnpm|yarn|node|cd|ls|cat|mkdir|rm|cp|mv|git)(?=\s|$)/g,
+				'$1<span class="keyword">$2</span>',
+			);
+		}
+
+		setHighlightedCode(highlighted);
+	});
+
+	const lineNumbers = () => {
+		if (!props.lineNumbers) return null;
+		const lines = props.code.split("\n");
+		return (
+			<div class="code-block-line-numbers">
+				<For each={lines}>
+					{(_, i) => <div class="line-number">{i() + 1}</div>}
+				</For>
+			</div>
+		);
+	};
+
+	const highlightLines = () => {
+		if (!props.highlightLines || props.highlightLines.length === 0) return "";
+		return props.highlightLines.map((line) => `.line-${line}`).join(", ");
+	};
+
+	return (
+		<div
+			class="code-block"
+			classList={{
+				"code-block-dark": props.theme === "dark" || props.theme === "auto",
+			}}
+		>
+			<Show when={props.filename || props.copyButton !== false}>
+				<div class="code-block-header">
+					<Show when={props.filename}>
+						<span class="code-block-filename">{props.filename}</span>
+					</Show>
+					<Show when={props.copyButton !== false}>
+						<button
+							type="button"
+							class="code-block-copy"
+							onClick={handleCopy}
+							aria-label={copied() ? "Copied!" : "Copy code"}
+						>
+							{copied() ? "✓" : "📋"}
+						</button>
+					</Show>
+				</div>
+			</Show>
+			<div class="code-block-content">
+				{lineNumbers()}
+				<pre class="code-block-pre">
+					<code
+						class={`code-block-code language-${props.language || "text"} ${highlightLines()}`}
+						innerHTML={highlightedCode()}
+					/>
+				</pre>
+			</div>
+		</div>
+	);
+};

package/src/presentation/solid/Toc.tsx

@@ -0,0 +1,58 @@
+/**
+ * Solid TOC Component
+ *
+ * Table of contents component for Solid
+ */
+
+import { For, Show } from "solid-js";
+import type { TocItem } from "../../modules/toc-generator";
+
+export interface TocProps {
+	/** TOC items */
+	items: TocItem[];
+	/** Active item ID */
+	activeId?: string;
+	/** On item click */
+	onItemClick?: (id: string) => void;
+	/** Max depth to show */
+	maxDepth?: number;
+}
+
+export const Toc = (props: TocProps) => {
+	const renderItem = (item: TocItem, depth = 0) => {
+		if (depth >= (props.maxDepth || 6)) return null;
+
+		const isActive = () => props.activeId === item.id;
+		const hasChildren = () => item.children && item.children.length > 0;
+
+		return (
+			<li class={`toc-item toc-level-${item.level}`}>
+				<a
+					href={`#${item.id}`}
+					class={`toc-link ${isActive() ? "toc-link-active" : ""}`}
+					onClick={(e) => {
+						e.preventDefault();
+						props.onItemClick?.(item.id);
+					}}
+				>
+					{item.text}
+				</a>
+				<Show when={hasChildren()}>
+					<ul class="toc-children">
+						<For each={item.children}>
+							{(child) => <>{renderItem(child, depth + 1)}</>}
+						</For>
+					</ul>
+				</Show>
+			</li>
+		);
+	};
+
+	return (
+		<nav class="toc">
+			<ul class="toc-list">
+				<For each={props.items}>{(item) => <>{renderItem(item)}</>}</For>
+			</ul>
+		</nav>
+	);
+};

package/src/presentation/solid/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Solid Presentation Components
+ *
+ * Framework-specific UI components for Solid
+ *
+ * Note: Components are .tsx files and should be imported directly in Solid projects
+ */
+
+export type { TocItem } from "../../modules/toc-generator";
+export { CodeBlock } from "./CodeBlock";
+export { Toc } from "./Toc";