@topik/core 0.1.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import { Guide, Wiki, WikiPage } from "@topik/schema";
+
+//#region src/config/collection.d.ts
+declare const collectionConfigSchema: z.ZodObject<{
+  id: z.ZodString;
+  title: z.ZodString;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+  id: string;
+  title: string;
+  tags?: string[] | undefined;
+}, {
+  id: string;
+  title: string;
+  tags?: string[] | undefined;
+}>;
+type CollectionConfig = z.infer<typeof collectionConfigSchema>;
+declare function parseCollectionConfig(raw: unknown): CollectionConfig;
+//#endregion
+//#region src/config/wiki.d.ts
+type WikiNavNode = string | {
+  group: string;
+  slug?: string;
+  icon?: string;
+  children: WikiNavNode[];
+} | {
+  tab: string;
+  slug?: string;
+  icon?: string;
+  children: WikiNavNode[];
+} | {
+  href: string;
+  title: string;
+  icon?: string;
+};
+declare const wikiConfigSchema: z.ZodObject<{
+  id: z.ZodString;
+  title: z.ZodString;
+  navigation: z.ZodOptional<z.ZodArray<z.ZodType<WikiNavNode, z.ZodTypeDef, unknown>, "many">>;
+  theme: z.ZodOptional<z.ZodObject<{
+    colors: z.ZodOptional<z.ZodObject<{
+      primary: z.ZodString;
+      light: z.ZodOptional<z.ZodString>;
+      dark: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+      primary: string;
+      light?: string | undefined;
+      dark?: string | undefined;
+    }, {
+      primary: string;
+      light?: string | undefined;
+      dark?: string | undefined;
+    }>>;
+    appearance: z.ZodOptional<z.ZodObject<{
+      default: z.ZodOptional<z.ZodEnum<["light", "dark", "system"]>>;
+    }, "strip", z.ZodTypeAny, {
+      default?: "dark" | "light" | "system" | undefined;
+    }, {
+      default?: "dark" | "light" | "system" | undefined;
+    }>>;
+  }, "strip", z.ZodTypeAny, {
+    colors?: {
+      primary: string;
+      light?: string | undefined;
+      dark?: string | undefined;
+    } | undefined;
+    appearance?: {
+      default?: "dark" | "light" | "system" | undefined;
+    } | undefined;
+  }, {
+    colors?: {
+      primary: string;
+      light?: string | undefined;
+      dark?: string | undefined;
+    } | undefined;
+    appearance?: {
+      default?: "dark" | "light" | "system" | undefined;
+    } | undefined;
+  }>>;
+}, "strip", z.ZodTypeAny, {
+  id: string;
+  title: string;
+  navigation?: WikiNavNode[] | undefined;
+  theme?: {
+    colors?: {
+      primary: string;
+      light?: string | undefined;
+      dark?: string | undefined;
+    } | undefined;
+    appearance?: {
+      default?: "dark" | "light" | "system" | undefined;
+    } | undefined;
+  } | undefined;
+}, {
+  id: string;
+  title: string;
+  navigation?: unknown[] | undefined;
+  theme?: {
+    colors?: {
+      primary: string;
+      light?: string | undefined;
+      dark?: string | undefined;
+    } | undefined;
+    appearance?: {
+      default?: "dark" | "light" | "system" | undefined;
+    } | undefined;
+  } | undefined;
+}>;
+type WikiConfig = z.infer<typeof wikiConfigSchema>;
+declare function parseWikiConfig(raw: unknown): WikiConfig;
+//#endregion
+//#region src/resource.d.ts
+type Resource = Guide | Wiki | WikiPage;
+type ResourceType = Resource["type"];
+//#endregion
+//#region src/compile/shared.d.ts
+interface CompileResult {
+  resources: Resource[];
+}
+//#endregion
+//#region src/compile/wiki.d.ts
+interface CompileWikiOptions {
+  dir: string;
+}
+declare function compileWiki(options: CompileWikiOptions): Promise<CompileResult>;
+//#endregion
+//#region src/compile/guide.d.ts
+interface CompileGuidesOptions {
+  dir: string;
+}
+declare function compileGuides(options: CompileGuidesOptions): Promise<CompileResult>;
+//#endregion
+//#region src/compile/index.d.ts
+interface CompileOptions {
+  dir: string;
+}
+declare function compile(options: CompileOptions): Promise<CompileResult>;
+//#endregion
+//#region src/validate.d.ts
+interface ValidationError {
+  resource: string;
+  path: string;
+  message: string;
+}
+interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+}
+/** Validate the resources produced by `compile` and the CLI export. */
+declare function validateResources(resources: readonly unknown[]): ValidationResult;
+//#endregion
+//#region src/watch.d.ts
+interface WatchOptions {
+  dir: string;
+  signal?: AbortSignal;
+}
+type UpdateListener = (key: string, resource: Resource) => void;
+type ErrorListener = (error: Error) => void;
+interface Watcher {
+  /** Current compiled resources, keyed by `Type/name`. */
+  resources: Map<string, Resource>;
+  on(event: "update", listener: UpdateListener): this;
+  on(event: "error", listener: ErrorListener): this;
+  off(event: "update", listener: UpdateListener): this;
+  off(event: "error", listener: ErrorListener): this;
+  close(): Promise<void>;
+}
+declare function watch(options: WatchOptions): Promise<Watcher>;
+//#endregion
+export { type CollectionConfig, type CompileGuidesOptions, type CompileOptions, type CompileResult, type CompileWikiOptions, type Resource, type ResourceType, type ValidationError, type ValidationResult, type WatchOptions, type Watcher, type WikiConfig, compile, compileGuides, compileWiki, parseCollectionConfig, parseWikiConfig, validateResources, watch };

package/dist/index.mjs

@@ -0,0 +1,430 @@
+import { z } from "zod";
+import { join, resolve } from "node:path";
+import { access, readFile, readdir } from "node:fs/promises";
+import { parse } from "yaml";
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { guideSchema, wikiPageSchema, wikiSchema } from "@topik/schema";
+import { EventEmitter } from "node:events";
+import { watch as watch$1 } from "chokidar";
+//#region src/config/collection.ts
+const collectionConfigSchema = z.object({
+	id: z.string().min(1).max(63).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+	title: z.string().min(1).max(256),
+	tags: z.array(z.string().min(1).max(63)).optional()
+});
+function parseCollectionConfig(raw) {
+	return collectionConfigSchema.parse(raw);
+}
+//#endregion
+//#region src/config/wiki.ts
+const wikiPagePath = z.string().min(1).max(512).regex(/^(?:[a-z0-9]+(?:-[a-z0-9]+)*)(?:\/(?:[a-z0-9]+(?:-[a-z0-9]+)*))*$/, "Wiki page paths must use lowercase DNS-style segments separated by '/'");
+const navNodeSchema = z.union([
+	wikiPagePath,
+	z.object({
+		group: z.string().min(1).max(256),
+		slug: z.string().min(1).max(256).optional(),
+		icon: z.string().min(1).max(256).optional(),
+		children: z.lazy(() => z.array(navNodeSchema)).default([])
+	}),
+	z.object({
+		tab: z.string().min(1).max(256),
+		slug: z.string().min(1).max(256).optional(),
+		icon: z.string().min(1).max(256).optional(),
+		children: z.lazy(() => z.array(navNodeSchema)).default([])
+	}),
+	z.object({
+		href: z.string().max(2048).refine((v) => v.startsWith("https://") || v.startsWith("http://"), { message: "href must be an http or https URL" }),
+		title: z.string().min(1).max(256),
+		icon: z.string().min(1).max(256).optional()
+	})
+]);
+const hexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/, "Must be a hex color (e.g. #ff73a8)");
+const themeSchema = z.object({
+	colors: z.object({
+		primary: hexColor,
+		light: hexColor.optional(),
+		dark: hexColor.optional()
+	}).optional(),
+	appearance: z.object({ default: z.enum([
+		"light",
+		"dark",
+		"system"
+	]).optional() }).optional()
+});
+const wikiConfigSchema = z.object({
+	id: z.string().min(1).max(63).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+	title: z.string().min(1).max(256),
+	navigation: z.array(navNodeSchema).optional(),
+	theme: themeSchema.optional()
+});
+function parseWikiConfig(raw) {
+	return wikiConfigSchema.parse(raw);
+}
+//#endregion
+//#region src/compile/config.ts
+async function readOptionalConfigFile(dir, candidates) {
+	for (const name of candidates) {
+		const filePath = join(dir, name);
+		let raw;
+		try {
+			raw = await readFile(filePath, "utf-8");
+		} catch (error) {
+			if (error.code === "ENOENT") continue;
+			throw new Error(`Failed to read config file ${filePath}`, { cause: error });
+		}
+		try {
+			return name.endsWith(".json") ? JSON.parse(raw) : parse(raw);
+		} catch (error) {
+			throw new Error(`Failed to parse config file ${filePath}`, { cause: error });
+		}
+	}
+}
+async function findConfigFile(dir, candidates) {
+	for (const name of candidates) try {
+		await access(join(dir, name));
+		return name;
+	} catch (error) {
+		if (error.code === "ENOENT") continue;
+		throw new Error(`Failed to access config file ${join(dir, name)}`, { cause: error });
+	}
+	return null;
+}
+//#endregion
+//#region src/compile/shared.ts
+const DNS_LABEL_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function parseMarkdownFrontmatter(raw, filePath) {
+	const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+	if (!match) return {
+		frontmatter: {},
+		content: raw
+	};
+	try {
+		const frontmatter = parse(match[1]);
+		if (frontmatter == null) return {
+			frontmatter: {},
+			content: match[2]
+		};
+		if (typeof frontmatter !== "object" || Array.isArray(frontmatter)) throw new Error("Frontmatter must parse to an object");
+		if ("title" in frontmatter && frontmatter.title != null && typeof frontmatter.title !== "string") throw new Error("Frontmatter title must be a string");
+		return {
+			frontmatter,
+			content: match[2]
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Invalid frontmatter in ${filePath}: ${message}`, { cause: error });
+	}
+}
+function extractMarkdownTitle(content, fallback) {
+	const match = content.match(/^#\s+(.+)$/m);
+	if (match) return match[1].trim();
+	return fallback.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function parseReferenceList(value, fieldName, filePath) {
+	if (value == null) return;
+	if (!Array.isArray(value)) throw new Error(`${fieldName} in ${filePath} must be an array of resource names`);
+	const references = value.map((entry, index) => {
+		if (typeof entry !== "string") throw new Error(`${fieldName}[${index}] in ${filePath} must be a string`);
+		if (entry.length > 63 || !DNS_LABEL_PATTERN.test(entry)) throw new Error(`${fieldName}[${index}] in ${filePath} must be a DNS-1123 resource name`);
+		return entry;
+	});
+	return references.length > 0 ? references : void 0;
+}
+//#endregion
+//#region src/compile/wiki.ts
+async function compileWiki(options) {
+	const dir = resolve(options.dir);
+	const raw = await readOptionalConfigFile(dir, [
+		"wiki.yaml",
+		"wiki.yml",
+		"wiki.json"
+	]);
+	if (raw == null) return { resources: [] };
+	const config = parseWikiConfig(raw);
+	const pagePaths = config.navigation ? [...new Set(collectPagePaths(config.navigation))] : [];
+	const fileContents = await Promise.all(pagePaths.map(async (pagePath) => {
+		return readFile(await resolveFilePath(dir, pagePath), "utf-8");
+	}));
+	const resources = [];
+	for (let i = 0; i < pagePaths.length; i++) {
+		const pagePath = pagePaths[i];
+		const { frontmatter, content } = parseMarkdownFrontmatter(fileContents[i], pagePath);
+		const name = pagePathToName(pagePath);
+		const title = typeof frontmatter.title === "string" ? frontmatter.title : extractMarkdownTitle(content, name);
+		const pageResource = {
+			apiVersion: "v1",
+			type: "WikiPage",
+			name: `${config.id}-${name}`,
+			spec: {
+				wiki: config.id,
+				title,
+				content: {
+					format: "topik",
+					value: content
+				}
+			}
+		};
+		resources.push(pageResource);
+	}
+	const wikiResource = {
+		apiVersion: "v1",
+		type: "Wiki",
+		name: config.id,
+		spec: {
+			title: config.title,
+			...config.navigation ? { navigation: resolveNavigation(config.navigation, config.id) } : {},
+			...config.theme ? { theme: config.theme } : {}
+		}
+	};
+	resources.push(wikiResource);
+	return { resources };
+}
+function collectPagePaths(nodes) {
+	const paths = [];
+	for (const node of nodes) if (typeof node === "string") paths.push(node);
+	else if ("group" in node || "tab" in node) paths.push(...collectPagePaths(node.children));
+	return paths;
+}
+async function resolveFilePath(dir, pagePath) {
+	for (const ext of [".mdx", ".md"]) {
+		const filePath = join(dir, pagePath + ext);
+		try {
+			await access(filePath);
+			return filePath;
+		} catch {}
+	}
+	throw new Error(`Page not found: ${pagePath} (tried .md and .mdx in ${dir})`);
+}
+function pagePathToSlug(pagePath) {
+	if (pagePath === "index") return "";
+	return pagePath.replace(/\/index$/, "");
+}
+function pagePathToName(pagePath) {
+	return pagePath.replace(/^\//, "").replaceAll("/", "-");
+}
+function resolveNavigation(nodes, wikiId) {
+	return nodes.map((node) => {
+		if (typeof node === "string") return {
+			type: "page",
+			page: `${wikiId}-${pagePathToName(node)}`,
+			slug: pagePathToSlug(node)
+		};
+		if ("group" in node || "tab" in node) {
+			const isTab = "tab" in node;
+			const title = isTab ? node.tab : node.group;
+			return {
+				type: isTab ? "tab" : "group",
+				title,
+				...node.slug ? { slug: node.slug } : {},
+				...node.icon ? { icon: node.icon } : {},
+				children: resolveNavigation(node.children, wikiId)
+			};
+		}
+		return {
+			type: "link",
+			title: node.title,
+			href: node.href,
+			...node.icon ? { icon: node.icon } : {}
+		};
+	});
+}
+//#endregion
+//#region src/compile/guide.ts
+async function compileGuides(options) {
+	const dir = resolve(options.dir);
+	const raw = await readOptionalConfigFile(dir, [
+		"collection.yaml",
+		"collection.yml",
+		"collection.json"
+	]);
+	if (raw == null) return { resources: [] };
+	const config = parseCollectionConfig(raw);
+	const markdownFiles = (await readdir(dir)).filter((f) => f.endsWith(".md") || f.endsWith(".mdx")).sort();
+	const resources = [];
+	for (const file of markdownFiles) {
+		const { frontmatter, content } = parseMarkdownFrontmatter(await readFile(join(dir, file), "utf-8"), file);
+		const slug = fileToSlug(file);
+		const name = `${config.id}-${slug}`;
+		const title = typeof frontmatter.title === "string" ? frontmatter.title : extractMarkdownTitle(content, slug);
+		const tags = mergeTags(config.tags, frontmatter.tags);
+		const authors = parseReferenceList(frontmatter.authors, "authors", file);
+		const description = typeof frontmatter.description === "string" ? frontmatter.description : void 0;
+		const guide = {
+			apiVersion: "v1",
+			type: "Guide",
+			name,
+			spec: {
+				title,
+				slug,
+				...description != null ? { description } : {},
+				...authors != null ? { authors } : {},
+				...tags.length > 0 ? { tags } : {},
+				content: {
+					format: "topik",
+					value: content
+				}
+			}
+		};
+		resources.push(guide);
+	}
+	return { resources };
+}
+function fileToSlug(filename) {
+	return filename.replace(/\.(mdx?|md)$/, "");
+}
+function mergeTags(collectionTags, frontmatterTags) {
+	const tags = /* @__PURE__ */ new Set();
+	if (collectionTags) for (const tag of collectionTags) tags.add(tag);
+	if (Array.isArray(frontmatterTags)) {
+		for (const tag of frontmatterTags) if (typeof tag === "string") tags.add(tag);
+	}
+	return [...tags];
+}
+//#endregion
+//#region src/compile/index.ts
+const WIKI_CONFIG_FILES = [
+	"wiki.yaml",
+	"wiki.yml",
+	"wiki.json"
+];
+const COLLECTION_CONFIG_FILES = [
+	"collection.yaml",
+	"collection.yml",
+	"collection.json"
+];
+async function compile(options) {
+	const dir = resolve(options.dir);
+	const resources = [];
+	if (await findConfigFile(dir, WIKI_CONFIG_FILES)) {
+		const result = await compileWiki({ dir });
+		resources.push(...result.resources);
+	}
+	if (await findConfigFile(dir, COLLECTION_CONFIG_FILES)) {
+		const result = await compileGuides({ dir });
+		resources.push(...result.resources);
+	}
+	return { resources };
+}
+//#endregion
+//#region src/validate.ts
+const ajv = new Ajv2020({
+	strict: true,
+	discriminator: true
+});
+addFormats(ajv);
+const validators = {
+	Guide: ajv.compile(guideSchema),
+	Wiki: ajv.compile(wikiSchema),
+	WikiPage: ajv.compile(wikiPageSchema)
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function getResourceLabel(resource) {
+	return `${typeof resource.type === "string" ? resource.type : "unknown"}/${typeof resource.name === "string" ? resource.name : "unknown"}`;
+}
+/** Validate the resources produced by `compile` and the CLI export. */
+function validateResources(resources) {
+	const errors = [];
+	for (const resource of resources) {
+		if (!isRecord(resource)) {
+			errors.push({
+				resource: "unknown/unknown",
+				path: "/",
+				message: "Resource must be an object"
+			});
+			continue;
+		}
+		if (typeof resource.type !== "string") {
+			errors.push({
+				resource: getResourceLabel(resource),
+				path: "/type",
+				message: "Resource type must be a string"
+			});
+			continue;
+		}
+		const validate = validators[resource.type];
+		if (!validate) {
+			errors.push({
+				resource: getResourceLabel(resource),
+				path: "/type",
+				message: `Unsupported resource type: ${resource.type}`
+			});
+			continue;
+		}
+		if (!validate(resource)) for (const err of validate.errors ?? []) errors.push({
+			resource: getResourceLabel(resource),
+			path: err.instancePath || "/",
+			message: err.message ?? "Unknown error"
+		});
+	}
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+//#endregion
+//#region src/watch.ts
+function resourceKey(resource) {
+	return `${resource.type}/${resource.name}`;
+}
+async function watch(options) {
+	const dir = resolve(options.dir);
+	const emitter = new EventEmitter();
+	const resources = /* @__PURE__ */ new Map();
+	const initial = await compile({ dir });
+	for (const resource of initial.resources) resources.set(resourceKey(resource), resource);
+	let debounceTimer = null;
+	async function recompile() {
+		try {
+			const result = await compile({ dir });
+			const newKeys = /* @__PURE__ */ new Set();
+			for (const resource of result.resources) {
+				const key = resourceKey(resource);
+				newKeys.add(key);
+				const existing = resources.get(key);
+				const serialized = JSON.stringify(resource);
+				if (!existing || JSON.stringify(existing) !== serialized) {
+					resources.set(key, resource);
+					emitter.emit("update", key, resource);
+				}
+			}
+			for (const key of resources.keys()) if (!newKeys.has(key)) resources.delete(key);
+		} catch (error) {
+			emitter.emit("error", error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	function scheduleRecompile() {
+		if (debounceTimer) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(recompile, 100);
+	}
+	const fsWatcher = watch$1(dir, {
+		ignoreInitial: true,
+		ignored: [/(^|[/\\])\../, "**/node_modules/**"]
+	});
+	fsWatcher.on("add", scheduleRecompile);
+	fsWatcher.on("change", scheduleRecompile);
+	fsWatcher.on("unlink", scheduleRecompile);
+	if (options.signal) options.signal.addEventListener("abort", () => {
+		fsWatcher.close();
+	});
+	const watcher = {
+		resources,
+		on(event, listener) {
+			emitter.on(event, listener);
+			return watcher;
+		},
+		off(event, listener) {
+			emitter.off(event, listener);
+			return watcher;
+		},
+		close: async () => {
+			if (debounceTimer) clearTimeout(debounceTimer);
+			await fsWatcher.close();
+		}
+	};
+	return watcher;
+}
+//#endregion
+export { compile, compileGuides, compileWiki, parseCollectionConfig, parseWikiConfig, validateResources, watch };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@topik/core",
+  "version": "0.1.0-alpha.1",
+  "description": "Topik core library",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "dependencies": {
+    "@topik/schema": "workspace:*",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "chokidar": "^4.0.0",
+    "yaml": "^2.7.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@typescript/native-preview": "catalog:",
+    "typescript": "catalog:",
+    "vite-plus": "catalog:",
+    "vitest": "catalog:"
+  }
+}