@wrikka/create-docs 0.1.0

package/src/runtime/types.ts

@@ -0,0 +1,217 @@
+/**
+ * Runtime types for the create-docs Solid app shell.
+ *
+ * A consumer injects a {@link DocsDataSource} so the UI stays
+ * source-agnostic: oRPC, static manifest, CMS, anything.
+ */
+
+export interface CollectionMeta {
+	id: string;
+	label: string;
+	icon?: string;
+	description?: string;
+	/** Optional repository URL used by "Edit on GitHub" etc. */
+	repoUrl?: string;
+	/** "docs" renders markdown pages, "api" renders the API reference layout, "showcase" renders cards. */
+	type?: "docs" | "api" | "showcase";
+	/** Sidebar sections (from `_dir.yml` or manual config) — ordered nav groups. */
+	sections?: {
+		id: string;
+		label: string;
+		icon?: string;
+		order?: number;
+		collapsed?: boolean;
+	}[];
+}
+
+export interface DocSeo {
+	title?: string;
+	description?: string;
+	image?: string;
+	ogType?: "article" | "website";
+	noIndex?: boolean;
+}
+
+/** Frontmatter parsed from a markdown document. */
+export interface DocFrontmatter {
+	title?: string;
+	description?: string;
+	/** Sort order within the sidebar/category. */
+	order?: number;
+	/** Sidebar category override. */
+	category?: string;
+	/** Hide from lists, search, sitemap and feeds (still renderable in dev). */
+	draft?: boolean;
+	/** ISO date — doc is hidden until this time (scheduled publishing). */
+	publishedAt?: string;
+	/** ISO date — shown as "last updated". */
+	lastUpdated?: string;
+	tags?: string[];
+	/** Small badge shown next to the sidebar label. */
+	badge?: string;
+	/** Iconify icon class for the sidebar entry. */
+	icon?: string;
+	/** Page-level overrides. */
+	toc?: boolean;
+	aside?: boolean;
+	editLink?: boolean;
+	layout?: "doc" | "page" | "home";
+	/** Per-page SEO overrides. */
+	seo?: DocSeo;
+	[key: string]: unknown;
+}
+
+/** One Markdown document. */
+export interface DocContent {
+	id: string;
+	label: string;
+	/** Body may be omitted in lightweight entries. */
+	content?: string;
+	category?: string;
+	order?: number;
+	icon?: string;
+	/** Optional badge shown in sidebar and search. */
+	badge?: string;
+	description?: string;
+	path?: string;
+	/** Optional tags for grouping/filtering. */
+	tags?: string[];
+	/** ISO date if available. */
+	date?: string;
+	/** Last-updated ISO timestamp. */
+	lastUpdated?: string;
+	/** Frontmatter values parsed from the file. */
+	frontmatter?: DocFrontmatter;
+}
+
+export interface DocEntry extends DocContent {
+	/** Sidebar category (required for grouping). */
+	category: string;
+	/** Short description. */
+	description: string;
+	/** Original file path / route path. */
+	path: string;
+	/** Support nested sidebar submenus. */
+	children?: DocEntry[];
+	/** Excluded from listings when the source filters drafts. */
+	draft?: boolean;
+	/** Original publication timestamp (ISO). */
+	publishedAt?: string;
+	/** Per-page SEO overrides. */
+	seo?: DocSeo;
+	/** Entry render type. */
+	type?: "doc" | "api" | "showcase" | "rust" | "npm" | "md";
+	/** Nav entries may omit the full body content. */
+	content?: string;
+}
+
+/** Nuxt Content-style query over a data source. */
+export interface DocQuery {
+	collection?: string;
+	/** Filters — all provided fields must match. */
+	where?: {
+		category?: string;
+		tag?: string;
+		draft?: boolean;
+	};
+	sort?: "title" | "order" | "lastUpdated" | "id";
+	order?: "asc" | "desc";
+	limit?: number;
+}
+
+/** Search result returned from buildSearchIndex(). */
+export interface SearchResult {
+	collection: string;
+	id: string;
+	title: string;
+	snippet: string;
+	score: number;
+}
+
+export interface AskInput {
+	collection: string;
+	id: string;
+	question: string;
+}
+
+export interface AskResult {
+	answer: string;
+	cost?: { tokens?: number; ms?: number };
+}
+
+/** Port — the app shell only talks to this interface. */
+export interface DocsDataSource {
+	/** Available collections. */
+	collections(): Promise<CollectionMeta[]> | CollectionMeta[];
+	/** List all documents in a collection. */
+	list(collection: string): Promise<DocEntry[]> | DocEntry[];
+	/** Fetch a single document. */
+	get(collection: string, id: string): Promise<DocContent> | DocContent;
+	/** Optional full-text search across collections. */
+	search?(
+		q: string,
+		collection?: string,
+	): Promise<SearchResult[]> | SearchResult[];
+	/** Optional — enables the Ask AI button when present. */
+	ask?(input: AskInput): Promise<AskResult> | AskResult;
+	/** Optional — Nuxt Content-style filtered/sorted document listing. */
+	query?(q: DocQuery): Promise<DocEntry[]> | DocEntry[];
+}
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+
+export interface ApiParameter {
+	name: string;
+	in: "query" | "path" | "header" | "cookie";
+	required: boolean;
+	description?: string;
+	schema?: unknown;
+	example?: unknown;
+}
+
+export interface GraphQlEndpoint {
+	/** GraphQL operation name. */
+	operation?: string;
+	/** GraphQL query or mutation. */
+	query: string;
+	/** Example / schema for variables. */
+	variables?: Record<string, unknown>;
+}
+
+export interface CliArg {
+	name: string;
+	required: boolean;
+	description?: string;
+	example?: string;
+}
+
+export interface CliEndpoint {
+	/** Base command, e.g. "wrikka". */
+	command: string;
+	/** Subcommand, e.g. "create". */
+	subcommand?: string;
+	args?: CliArg[];
+}
+
+export interface ApiEndpoint {
+	id: string;
+	method: HttpMethod;
+	path: string;
+	summary?: string;
+	description?: string;
+	tag?: string;
+	parameters: ApiParameter[];
+	requestBody?: {
+		description?: string;
+		required: boolean;
+		example?: unknown;
+		contentType?: string;
+	};
+	responses: Record<string, { description: string; example?: unknown }>;
+	/** Absolute base URL used by the playground. Defaults to origin. */
+	server?: string;
+	/** GraphQL-specific payload. */
+	graphql?: GraphQlEndpoint;
+	/** CLI-specific payload. */
+	cli?: CliEndpoint;
+}

package/src/search/index.ts

@@ -0,0 +1,6 @@
+export type SearchEntry = unknown;
+export type SearchIndex = unknown;
+export const buildSearchIndex = () => null;
+export const indexPages = () => null;
+export const pageToSearchEntry = () => null;
+export const search = () => null;

package/src/seo-optimization/index.ts

@@ -0,0 +1,4 @@
+export type MetaTagGenerator = unknown;
+export type MetaTags = unknown;
+export type SeoOptions = unknown;
+export const optimizeSeo = () => null;

package/src/shared/constants/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Compile-time static constants. These are the only safe values
+ * to import in the domain layer (where I/O is forbidden).
+ */
+
+export const DEFAULT_DOCS_DIR = "docs" as const;
+export const DEFAULT_BASE_ROUTE = "/docs" as const;
+export const DEFAULT_PORT = 5173 as const;
+export const VIRTUAL_PREFIX = "virtual:docs/" as const;
+export const PLUGIN_NAME = "vite-plugin-docs" as const;
+
+export const SUPPORTED_EXTENSIONS = [".md", ".mdoc"] as const;
+export const FRONTMATTER_DELIMITER = "---" as const;
+
+export const SEARCH_CONTENT_LIMIT = 500 as const;
+export const SIDEBAR_DEFAULT_GROUP_TITLE = "Documentation" as const;
+export const SIDEBAR_DEFAULT_ORDER = 999 as const;
+
+export const BADGE_VARIANTS = [
+	"default",
+	"success",
+	"warning",
+	"danger",
+] as const;
+export const API_AUTH_TYPES = ["bearer", "apiKey", "oauth2"] as const;
+export const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;

package/src/shared/errors/index.ts

@@ -0,0 +1,195 @@
+/**
+ * Domain error types — tagged unions for typed failures.
+ *
+ * Each module can extend this with its own error variants, but
+ * all errors should flow through these base types at boundaries.
+ */
+
+export type AppErrorKind =
+	| "file_not_found"
+	| "parse_error"
+	| "validation_error"
+	| "config_error"
+	| "io_error"
+	| "plugin_error";
+
+export interface AppError {
+	readonly kind: AppErrorKind;
+	readonly message: string;
+	readonly cause?: unknown;
+	readonly context?: Readonly<Record<string, unknown>>;
+	/** JSON-pointer-like path to the offending field (e.g. "site.title"). */
+	readonly path?: string;
+	/** Actionable hint shown to the user (e.g. allowed values). */
+	readonly hint?: string;
+	/** Documentation URL related to this error. */
+	readonly docsUrl?: string;
+	/** Allowed values, for inline suggestions. */
+	readonly suggestions?: readonly string[];
+}
+
+const DOCS_BASE = "https://create-docs.dev/errors";
+
+export const makeError = (
+	kind: AppErrorKind,
+	message: string,
+	options?: {
+		cause?: unknown;
+		context?: Record<string, unknown>;
+		path?: string;
+		hint?: string;
+		suggestions?: readonly string[];
+	},
+): AppError => {
+	const base: {
+		kind: AppErrorKind;
+		message: string;
+		cause?: unknown;
+		context?: Readonly<Record<string, unknown>>;
+		path?: string;
+		hint?: string;
+		suggestions?: readonly string[];
+		docsUrl: string;
+	} = {
+		kind,
+		message,
+		docsUrl: `${DOCS_BASE}/${kind.replace(/_/g, "-")}`,
+	};
+	if (options?.cause !== undefined) base.cause = options.cause;
+	if (options?.context !== undefined) base.context = options.context;
+	if (options?.path !== undefined) base.path = options.path;
+	if (options?.hint !== undefined) base.hint = options.hint;
+	if (options?.suggestions !== undefined)
+		base.suggestions = options.suggestions;
+	return base;
+};
+
+export const fileNotFound = (path: string, cause?: unknown): AppError =>
+	makeError("file_not_found", `File not found: ${path}`, {
+		cause,
+		context: { path },
+		hint: "Check that the docsDir option points to an existing directory.",
+	});
+
+export const parseError = (
+	path: string,
+	message: string,
+	cause?: unknown,
+): AppError =>
+	makeError("parse_error", message, {
+		cause,
+		context: { path },
+		hint: "Verify the frontmatter is delimited by '---' on its own line.",
+	});
+
+export const validationError = (
+	message: string,
+	options?: {
+		path?: string;
+		suggestions?: readonly string[];
+		context?: Record<string, unknown>;
+	},
+): AppError => {
+	const ctx = options?.context ?? {};
+	if (options?.path !== undefined) ctx.path = options.path;
+	return makeError("validation_error", message, {
+		context: ctx,
+		path: options?.path,
+		suggestions: options?.suggestions,
+		hint: options?.suggestions?.length
+			? `Did you mean one of: ${options.suggestions.join(", ")}?`
+			: undefined,
+	});
+};
+
+export const configError = (
+	message: string,
+	options?: {
+		path?: string;
+		suggestions?: readonly string[];
+		context?: Record<string, unknown>;
+		hint?: string;
+		cause?: unknown;
+	},
+): AppError => {
+	const ctx = options?.context ?? {};
+	if (options?.path !== undefined) ctx.path = options.path;
+	return makeError("config_error", message, {
+		context: ctx,
+		path: options?.path,
+		suggestions: options?.suggestions,
+		hint:
+			options?.hint ??
+			(options?.suggestions?.length
+				? `Allowed: ${options.suggestions.join(", ")}.`
+				: "See https://create-docs.dev/docs/configuration for the full schema."),
+		cause: options?.cause,
+	});
+};
+
+export const ioError = (
+	path: string,
+	message: string,
+	cause?: unknown,
+): AppError => makeError("io_error", message, { cause, context: { path } });
+
+export const pluginError = (
+	message: string,
+	options?: {
+		path?: string;
+		hint?: string;
+		context?: Record<string, unknown>;
+		cause?: unknown;
+	},
+): AppError => {
+	const ctx = options?.context ?? {};
+	if (options?.path !== undefined) ctx.path = options.path;
+	return makeError("plugin_error", message, {
+		context: ctx,
+		path: options?.path,
+		hint: options?.hint,
+		cause: options?.cause,
+	});
+};
+
+const RED = "\u001B[31m";
+const YELLOW = "\u001B[33m";
+const CYAN = "\u001B[36m";
+const DIM = "\u001B[2m";
+const RESET = "\u001B[0m";
+const BOLD = "\u001B[1m";
+
+const isColorSupported = (): boolean => {
+	if (typeof process === "undefined") return false;
+	const env = process.env;
+	if (env?.NO_COLOR && env.NO_COLOR.length > 0) return false;
+	if (env?.FORCE_COLOR && env.FORCE_COLOR.length > 0) return true;
+	return Boolean(process.stdout?.isTTY);
+};
+
+/** Format an AppError as a multi-line, ANSI-coloured, actionable message. */
+export const formatError = (
+	e: AppError,
+	color: boolean = isColorSupported(),
+): string => {
+	const c = (code: string, s: string): string =>
+		color ? `${code}${s}${RESET}` : s;
+	const lines: string[] = [];
+	lines.push(`${c(BOLD + RED, "✖")} ${c(BOLD, e.message)}`);
+	lines.push(`  ${c(DIM, "kind:")} ${e.kind}`);
+	if (e.path) lines.push(`  ${c(DIM, "path:")} ${e.path}`);
+	if (e.suggestions && e.suggestions.length > 0) {
+		lines.push(
+			`  ${c(DIM, "allowed:")} ${e.suggestions.map((s) => c(CYAN, s)).join(", ")}`,
+		);
+	}
+	if (e.hint) lines.push(`  ${c(YELLOW, "hint:")} ${e.hint}`);
+	if (e.docsUrl) lines.push(`  ${c(DIM, "docs:")} ${c(CYAN, e.docsUrl)}`);
+	if (e.context && Object.keys(e.context).length > 0) {
+		lines.push(`  ${c(DIM, "context:")} ${JSON.stringify(e.context)}`);
+	}
+	if (e.cause !== undefined) {
+		lines.push(`  ${c(DIM, "cause:")} ${String(e.cause)}`);
+	}
+	return lines.join("\n");
+};

package/src/shared/index.ts

@@ -0,0 +1,27 @@
+export {
+	API_AUTH_TYPES,
+	BADGE_VARIANTS,
+	DEFAULT_BASE_ROUTE,
+	DEFAULT_DOCS_DIR,
+	DEFAULT_PORT,
+	FRONTMATTER_DELIMITER,
+	HTTP_METHODS,
+	PLUGIN_NAME,
+	SEARCH_CONTENT_LIMIT,
+	SIDEBAR_DEFAULT_GROUP_TITLE,
+	SIDEBAR_DEFAULT_ORDER,
+	SUPPORTED_EXTENSIONS,
+	VIRTUAL_PREFIX,
+} from "./constants";
+export {
+	configError,
+	fileNotFound,
+	formatError,
+	ioError,
+	makeError,
+	parseError,
+	pluginError,
+	validationError,
+} from "./errors";
+export * from "./types";
+export * from "./utils";

package/src/shared/types/brand.ts

@@ -0,0 +1,14 @@
+/**
+ * Brand<T, B> — A nominal type for primitives (preventing ID mixups at compile time).
+ *
+ * @example
+ *   type UserId = Brand<string, 'UserId'>;
+ *   type PostId = Brand<string, 'PostId'>;
+ *   const get = (id: UserId) => ...;
+ *   get('abc' as UserId); // OK
+ *   get('abc' as PostId); // compile error
+ */
+export type Brand<T, B extends string> = T & { readonly __brand: B };
+
+export const brand = <T, B extends string>(value: T): Brand<T, B> =>
+	value as Brand<T, B>;

package/src/shared/types/client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Ambient type declarations for the `virtual:docs/*` modules.
+ * Import this from your tsconfig (or include it in your project's types)
+ * to get full autocomplete on the virtual module imports.
+ */
+declare module "virtual:docs/data" {
+	import type { DocPage } from "@create-docs/modules/content";
+	export const docsData: ReadonlyArray<{
+		id: string;
+		slug: string;
+		title: string;
+		description?: string;
+		frontmatter: DocPage["frontmatter"];
+		rawContent: string;
+		content: string;
+		filePath: string;
+	}>;
+}
+
+declare module "virtual:docs/sidebar" {
+	import type { SidebarGroup } from "@create-docs/modules/navigation";
+	export const sidebar: readonly SidebarGroup[];
+}
+
+declare module "virtual:docs/nav" {
+	import type { NavSection } from "@create-docs/modules/navigation";
+	export const nav: readonly NavSection[];
+}
+
+declare module "virtual:docs/search-index" {
+	import type { SearchEntry } from "@create-docs/modules/search";
+	export const searchIndex: readonly SearchEntry[];
+}
+
+declare module "virtual:docs/config" {
+	import type { ResolvedDocsConfig } from "@create-docs/modules/config";
+	export const docsConfig: ResolvedDocsConfig;
+	export const site: ResolvedDocsConfig["site"];
+	export const nav: ResolvedDocsConfig["nav"];
+	export const sidebar: ResolvedDocsConfig["sidebar"];
+	export const api: ResolvedDocsConfig["api"];
+	export const search: ResolvedDocsConfig["search"];
+	export const editLink: ResolvedDocsConfig["editLink"];
+	export const lastUpdated: ResolvedDocsConfig["lastUpdated"];
+}

package/src/shared/types/either.ts

@@ -0,0 +1,38 @@
+/**
+ * Either<L, R> — A pure algebraic data type for a value that can be one of two types.
+ *
+ * Convention: L = "left" (often an error/short-circuit), R = "right" (success/continuation).
+ *
+ * Use this when you need to model two valid outcomes (e.g., a value OR a reason it isn't applicable)
+ * without committing to Result's "err" semantics.
+ */
+export type Either<L, R> =
+	| { readonly tag: "left"; readonly left: L }
+	| { readonly tag: "right"; readonly right: R };
+
+export const left = <L>(value: L): Either<L, never> => ({
+	tag: "left",
+	left: value,
+});
+
+export const right = <R>(value: R): Either<never, R> => ({
+	tag: "right",
+	right: value,
+});
+
+export const isLeft = <L, R>(e: Either<L, R>): e is { tag: "left"; left: L } =>
+	e.tag === "left";
+
+export const isRight = <L, R>(
+	e: Either<L, R>,
+): e is { tag: "right"; right: R } => e.tag === "right";
+
+export const map = <L, R, R2>(
+	e: Either<L, R>,
+	fn: (right: R) => R2,
+): Either<L, R2> => (e.tag === "right" ? right(fn(e.right)) : e);
+
+export const mapLeft = <L, L2, R>(
+	e: Either<L, R>,
+	fn: (left: L) => L2,
+): Either<L2, R> => (e.tag === "left" ? left(fn(e.left)) : e);

package/src/shared/types/index.ts

@@ -0,0 +1,42 @@
+export type { Brand } from "./brand";
+export { brand } from "./brand";
+export type { Either } from "./either";
+export {
+	isLeft,
+	isRight,
+	left,
+	map as mapEither,
+	mapLeft,
+	right,
+} from "./either";
+export type { Option } from "./option";
+
+export {
+	filter,
+	flatMap as flatMapOption,
+	fromNullable,
+	fromPredicate,
+	getOrElse,
+	isNone,
+	isSome,
+	map as mapOption,
+	none,
+	orElse,
+	some,
+	toNullable,
+} from "./option";
+export type { Result } from "./result";
+export {
+	all,
+	err,
+	flatMap as flatMapResult,
+	fromThrowable,
+	isErr,
+	isOk,
+	map as mapResult,
+	mapErr,
+	ok,
+	partition,
+	unwrap,
+	unwrapOr,
+} from "./result";

package/src/shared/types/option.ts

@@ -0,0 +1,52 @@
+/**
+ * Option<T> — A pure algebraic data type for values that may be absent.
+ *
+ * Use this to model nullable values without `null | undefined` leakage.
+ *
+ * @example
+ *   const findUser = (id: string): Option<User> =>
+ *     users.has(id) ? some(users.get(id)!) : none;
+ */
+export type Option<T> =
+	| { readonly kind: "some"; readonly value: T }
+	| { readonly kind: "none" };
+
+export const some = <T>(value: T): Option<T> => ({ kind: "some", value });
+
+export const none = <T = never>(): Option<T> => ({ kind: "none" });
+
+export const isSome = <T>(o: Option<T>): o is { kind: "some"; value: T } =>
+	o.kind === "some";
+
+export const isNone = <T>(o: Option<T>): o is { kind: "none" } =>
+	o.kind === "none";
+
+export const map = <T, U>(o: Option<T>, fn: (value: T) => U): Option<U> =>
+	o.kind === "some" ? some(fn(o.value)) : o;
+
+export const flatMap = <T, U>(
+	o: Option<T>,
+	fn: (value: T) => Option<U>,
+): Option<U> => (o.kind === "some" ? fn(o.value) : o);
+
+export const filter = <T>(
+	o: Option<T>,
+	pred: (value: T) => boolean,
+): Option<T> => (o.kind === "some" && pred(o.value) ? o : none());
+
+export const orElse = <T>(o: Option<T>, fallback: Option<T>): Option<T> =>
+	o.kind === "some" ? o : fallback;
+
+export const getOrElse = <T>(o: Option<T>, fallback: T): T =>
+	o.kind === "some" ? o.value : fallback;
+
+export const toNullable = <T>(o: Option<T>): T | null =>
+	o.kind === "some" ? o.value : null;
+
+export const fromNullable = <T>(value: T | null | undefined): Option<T> =>
+	value === null || value === undefined ? none() : some(value);
+
+export const fromPredicate = <T>(
+	value: T,
+	pred: (v: T) => boolean,
+): Option<T> => (pred(value) ? some(value) : none());