@opendocsdev/cli 0.2.0

package/src/engine/src/lib/config.ts

@@ -0,0 +1,79 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { DocsConfig } from "../../../config/schema.js";
+
+/**
+ * Get the project directory from environment variable or fallback to cwd
+ */
+export function getProjectDir(): string {
+  return process.env.OPENDOCS_PROJECT_DIR || process.cwd();
+}
+
+// Cache for loaded configuration to avoid repeated file reads
+let cachedConfig: DocsConfig | null = null;
+let cachedConfigPath: string | null = null;
+
+/**
+ * Load and parse the docs.json configuration file from the project directory.
+ * Results are cached to prevent re-reading on every component render.
+ * Caching is disabled in development mode to allow hot-reloading of config changes.
+ */
+export async function loadConfig(): Promise<DocsConfig> {
+  const projectDir = getProjectDir();
+  const configPath = path.join(projectDir, "docs.json");
+  const isDev = process.env.NODE_ENV !== "production";
+
+  // Return cached config if available, path hasn't changed, and not in dev mode
+  if (cachedConfig && cachedConfigPath === configPath && !isDev) {
+    return cachedConfig;
+  }
+
+  try {
+    const configContent = await fs.readFile(configPath, "utf-8");
+    cachedConfig = JSON.parse(configContent) as DocsConfig;
+    cachedConfigPath = configPath;
+    return cachedConfig;
+  } catch {
+    // Return minimal default config if docs.json is not found
+    const defaultConfig: DocsConfig = {
+      name: "Documentation",
+      navigation: [],
+      snippets: ["snippets"],
+    };
+    cachedConfig = defaultConfig;
+    cachedConfigPath = configPath;
+    return defaultConfig;
+  }
+}
+
+/**
+ * Clear the config cache. Useful for development/hot-reload scenarios.
+ */
+export function clearConfigCache(): void {
+  cachedConfig = null;
+  cachedConfigPath = null;
+}
+
+/**
+ * Get the path to the user's content directory
+ */
+export function getContentDir(): string {
+  return getProjectDir();
+}
+
+/**
+ * Get the path to the user's public assets directory
+ */
+export function getPublicDir(): string {
+  return path.join(getProjectDir(), "public");
+}
+
+/**
+ * Get the path to an MDX file in the user's project
+ */
+export function getMdxPath(pagePath: string): string {
+  const projectDir = getProjectDir();
+  // Add .mdx extension if not present
+  const fileName = pagePath.endsWith(".mdx") ? pagePath : `${pagePath}.mdx`;
+  return path.join(projectDir, fileName);
+}

package/src/engine/src/lib/markdown.ts

@@ -0,0 +1,54 @@
+export interface Frontmatter {
+  title?: string;
+  description?: string;
+  [key: string]: string | undefined;
+}
+
+export interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+
+/**
+ * Parse frontmatter from markdown/MDX content
+ */
+export function parseFrontmatter(content: string): {
+  frontmatter: Frontmatter;
+  body: string;
+} {
+  // Match frontmatter: starts with ---, optional content, ends with ---
+  const match = content.match(/^---[\r\n]+([\s\S]*?)[\r\n]*---[\r\n]*/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const fm: Frontmatter = {};
+  const frontmatterContent = match[1].trim();
+  if (frontmatterContent) {
+    for (const line of frontmatterContent.split("\n")) {
+      const m = line.match(/^(\w+):\s*["']?(.+?)["']?\s*$/);
+      if (m) fm[m[1]] = m[2];
+    }
+  }
+  return { frontmatter: fm, body: content.slice(match[0].length).trim() };
+}
+
+/**
+ * Extract headings from markdown content for table of contents
+ */
+export function extractHeadings(content: string): Heading[] {
+  const headings: Heading[] = [];
+  const regex = /^(#{2,6})\s+(.+)$/gm;
+  let m;
+  while ((m = regex.exec(content)) !== null) {
+    const text = m[2].trim();
+    headings.push({
+      depth: m[1].length,
+      text,
+      slug: text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/(^-|-$)/g, ""),
+    });
+  }
+  return headings;
+}

package/src/engine/src/lib/mdx-loader.ts

@@ -0,0 +1,143 @@
+/**
+ * MDX Loader - Dynamically imports MDX files from user's content directory
+ * Uses the @content Vite alias which points to OPENDOCS_PROJECT_DIR
+ */
+
+import type { AstroComponentFactory } from "astro/runtime/server/index.js";
+import {
+  isSnippetPath as isSnippetPathUtil,
+  extractSlugFromPath as extractSlugFromPathUtil,
+  filterPathsToSlugs as filterPathsToSlugsUtil,
+} from "./mdx-utils.js";
+
+export interface Frontmatter {
+  title?: string;
+  description?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Props for the MDX Content component
+ * The components prop allows injecting custom components for MDX rendering
+ */
+export interface ContentProps {
+  components?: Record<string, AstroComponentFactory>;
+}
+
+export interface MDXModule {
+  default: AstroComponentFactory;
+  frontmatter?: Frontmatter;
+}
+
+export interface LoadedMDX {
+  Content: AstroComponentFactory;
+  frontmatter: Frontmatter;
+}
+
+// Get configured snippet folders from environment variable (set by dev.ts/build.ts)
+// Default to ["snippets"] if not configured
+function getSnippetFolders(): string[] {
+  const snippetsEnv = import.meta.env.OPENDOCS_SNIPPETS;
+  if (snippetsEnv) {
+    try {
+      return JSON.parse(snippetsEnv);
+    } catch {
+      // Invalid JSON in env var, fall back to default
+      return ["snippets"];
+    }
+  }
+  return ["snippets"];
+}
+
+const snippetFolders = getSnippetFolders();
+
+// Get all MDX files from user's content directory
+// This glob pattern is resolved at build time via the @content Vite alias
+const mdxModules = import.meta.glob<MDXModule>("@content/**/*.mdx");
+const mdModules = import.meta.glob<MDXModule>("@content/**/*.md");
+
+/**
+ * Check if a path is in a configured snippet folder
+ * Uses default snippet folders from environment
+ */
+function isSnippetPath(path: string): boolean {
+  return isSnippetPathUtil(path, snippetFolders);
+}
+
+/**
+ * Extract slug from a glob path
+ * Handles both @content/... and relative paths like ../../../../test-docs/...
+ * Returns null for paths in configured snippet folders (they should not become pages)
+ * Uses default snippet folders from environment
+ */
+function extractSlugFromPath(globPath: string): string | null {
+  return extractSlugFromPathUtil(globPath, snippetFolders);
+}
+
+/**
+ * Build a map of slug -> loader function
+ * Excludes files in configured snippet folders
+ */
+function buildSlugMap(): Map<string, () => Promise<MDXModule>> {
+  const slugMap = new Map<string, () => Promise<MDXModule>>();
+
+  for (const [path, loader] of Object.entries(mdxModules)) {
+    const slug = extractSlugFromPath(path);
+    // Skip snippet folder paths (extractSlugFromPath returns null for these)
+    if (slug !== null) {
+      slugMap.set(slug, loader);
+    }
+  }
+
+  for (const [path, loader] of Object.entries(mdModules)) {
+    const slug = extractSlugFromPath(path);
+    // Skip snippet folder paths and don't override .mdx with .md
+    if (slug !== null && !slugMap.has(slug)) {
+      slugMap.set(slug, loader);
+    }
+  }
+
+  return slugMap;
+}
+
+// Build the slug map once at module load time
+const slugMap = buildSlugMap();
+
+/**
+ * Load an MDX file by slug (e.g., "introduction" or "api/reference")
+ * Returns the Content component and frontmatter
+ */
+export async function loadMDX(slug: string): Promise<LoadedMDX | null> {
+  const loader = slugMap.get(slug);
+
+  if (!loader) {
+    console.error(`MDX file not found for slug: ${slug}`);
+    console.error("Available slugs:", Array.from(slugMap.keys()));
+    return null;
+  }
+
+  try {
+    const module = await loader();
+    return {
+      Content: module.default,
+      frontmatter: module.frontmatter || {},
+    };
+  } catch (error) {
+    console.error(`Error loading MDX for slug ${slug}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Get all available content slugs (for static path generation)
+ */
+export function getAvailableSlugs(): string[] {
+  return Array.from(slugMap.keys());
+}
+
+// Re-export pure utility functions for testing purposes
+export {
+  isSnippetPath as isSnippetPathUtil,
+  extractSlugFromPath as extractSlugFromPathUtil,
+  filterPathsToSlugs as filterPathsToSlugsUtil,
+} from "./mdx-utils.js";

package/src/engine/src/lib/mdx-utils.ts

@@ -0,0 +1,72 @@
+/**
+ * MDX Utility Functions - Pure functions for path and slug manipulation
+ * Extracted from mdx-loader.ts for testability
+ */
+
+/**
+ * Check if a path is in a configured snippet folder
+ */
+export function isSnippetPath(path: string, folders: string[]): boolean {
+  return folders.some(
+    (folder) => path.includes(`/${folder}/`) || path.startsWith(`${folder}/`)
+  );
+}
+
+/**
+ * Extract slug from a glob path
+ * Handles both @content/... and relative paths like ../../../../test-docs/...
+ * Returns null for paths in configured snippet folders (they should not become pages)
+ */
+export function extractSlugFromPath(
+  globPath: string,
+  folders: string[]
+): string | null {
+  // Remove @content/ prefix if present
+  if (globPath.startsWith("@content/")) {
+    const relativePath = globPath.replace(/^@content\//, "");
+    // Check if this is a snippet folder path
+    if (isSnippetPath(relativePath, folders)) {
+      return null;
+    }
+    return relativePath.replace(/\.mdx?$/, "");
+  }
+
+  // Handle relative paths - check if in snippet folder
+  if (isSnippetPath(globPath, folders)) {
+    return null;
+  }
+
+  // Handle relative paths from Vite glob
+  // e.g., "../../../../test-docs/guides/using-snippets.mdx" -> "guides/using-snippets"
+  // e.g., "../../../../test-docs/components.mdx" -> "components"
+  // Find the project directory boundary (last ../ followed by project-dir/)
+  // The pattern matches all the "../" parts, then project-dir/, then captures the slug
+  const relativeMatch = globPath.match(/(?:\.\.\/)+[^/]+\/(.+)\.mdx?$/);
+  if (relativeMatch) {
+    return relativeMatch[1];
+  }
+
+  // Fallback: just extract filename
+  const filenameMatch = globPath.match(/\/([^/]+)\.mdx?$/);
+  if (filenameMatch) {
+    return filenameMatch[1];
+  }
+
+  // Fallback: just remove extension
+  return globPath.replace(/\.mdx?$/, "");
+}
+
+/**
+ * Filter paths and return valid slugs (excludes snippet folders)
+ * Used for testing purposes
+ */
+export function filterPathsToSlugs(paths: string[], folders: string[]): string[] {
+  const slugs: string[] = [];
+  for (const path of paths) {
+    const slug = extractSlugFromPath(path, folders);
+    if (slug !== null && !slugs.includes(slug)) {
+      slugs.push(slug);
+    }
+  }
+  return slugs;
+}

package/src/engine/src/lib/remark-opendocs.ts

@@ -0,0 +1,195 @@
+/**
+ * Unified remark plugin for opendocs MDX transformations.
+ * Handles all custom AST modifications in a single pass.
+ */
+import { visit } from "unist-util-visit";
+import type { Root } from "mdast";
+
+interface MdxJsxAttribute {
+  type: "mdxJsxAttribute";
+  name: string;
+  value: string | { type: string; value: string } | null;
+}
+
+interface MdxJsxFlowElement {
+  type: "mdxJsxFlowElement";
+  name: string | null;
+  attributes: MdxJsxAttribute[];
+  children: unknown[];
+}
+
+interface CodeNode {
+  type: "code";
+  lang?: string | null;
+  meta?: string | null;
+  value: string;
+}
+
+// ============================================
+// Type Guards
+// ============================================
+
+function isMdxJsxFlowElement(node: unknown): node is MdxJsxFlowElement {
+  return (
+    typeof node === "object" &&
+    node !== null &&
+    (node as { type?: string }).type === "mdxJsxFlowElement"
+  );
+}
+
+function isCodeNode(node: unknown): node is CodeNode {
+  return (
+    typeof node === "object" &&
+    node !== null &&
+    (node as { type?: string }).type === "code"
+  );
+}
+
+// ============================================
+// CodeGroup: Extract code block labels
+// ============================================
+
+function extractCodeLabels(children: unknown[]): string[] {
+  const labels: string[] = [];
+
+  function traverse(nodes: unknown[]) {
+    for (const node of nodes) {
+      if (isCodeNode(node)) {
+        const label = node.meta || node.lang || "code";
+        labels.push(label);
+      } else if (
+        typeof node === "object" &&
+        node !== null &&
+        Array.isArray((node as { children?: unknown[] }).children)
+      ) {
+        traverse((node as { children: unknown[] }).children);
+      }
+    }
+  }
+
+  traverse(children);
+  return labels;
+}
+
+function processCodeGroup(node: MdxJsxFlowElement) {
+  const labels = extractCodeLabels(node.children);
+  if (labels.length === 0) return;
+
+  node.attributes = node.attributes || [];
+  node.attributes.push({
+    type: "mdxJsxAttribute",
+    name: "data-labels",
+    value: JSON.stringify(labels),
+  });
+  node.attributes.push({
+    type: "mdxJsxAttribute",
+    name: "data-sync-key",
+    value: labels.slice().sort().join(":"),
+  });
+}
+
+// ============================================
+// Tabs: Extract tab labels and icons
+// ============================================
+
+interface TabInfo {
+  label: string;
+  icon?: string;
+}
+
+function getAttributeValue(
+  attributes: MdxJsxAttribute[],
+  name: string
+): string | undefined {
+  const attr = attributes.find((a) => a.name === name);
+  if (!attr) return undefined;
+  if (typeof attr.value === "string") return attr.value;
+  if (attr.value && typeof attr.value === "object" && "value" in attr.value) {
+    return attr.value.value;
+  }
+  return undefined;
+}
+
+function extractTabsInfo(children: unknown[]): TabInfo[] {
+  const tabs: TabInfo[] = [];
+  for (const child of children) {
+    if (isMdxJsxFlowElement(child) && child.name === "Tab") {
+      const label = getAttributeValue(child.attributes, "label");
+      const icon = getAttributeValue(child.attributes, "icon");
+      if (label) tabs.push({ label, icon });
+    }
+  }
+  return tabs;
+}
+
+function processTabs(node: MdxJsxFlowElement) {
+  const tabsInfo = extractTabsInfo(node.children);
+  if (tabsInfo.length === 0) return;
+
+  node.attributes = node.attributes || [];
+  node.attributes.push({
+    type: "mdxJsxAttribute",
+    name: "data-tabs",
+    value: JSON.stringify(tabsInfo),
+  });
+}
+
+// ============================================
+// React Hooks: Auto-inject imports
+// ============================================
+
+const REACT_HOOKS_IMPORT = {
+  type: "mdxjsEsm",
+  value: `import { useState, useEffect, useMemo, useCallback, useRef, useContext, useReducer, Fragment } from 'react';`,
+  data: {
+    estree: {
+      type: "Program",
+      sourceType: "module",
+      body: [
+        {
+          type: "ImportDeclaration",
+          specifiers: [
+            "useState",
+            "useEffect",
+            "useMemo",
+            "useCallback",
+            "useRef",
+            "useContext",
+            "useReducer",
+            "Fragment",
+          ].map((name) => ({
+            type: "ImportSpecifier",
+            imported: { type: "Identifier", name },
+            local: { type: "Identifier", name },
+          })),
+          source: { type: "Literal", value: "react" },
+        },
+      ],
+    },
+  },
+};
+
+// ============================================
+// Main Plugin
+// ============================================
+
+export function remarkOpendocs() {
+  return (tree: Root) => {
+    // Inject React hooks import at the beginning
+    tree.children.unshift(REACT_HOOKS_IMPORT as any);
+
+    // Process component-specific transformations
+    visit(tree, (node) => {
+      if (!isMdxJsxFlowElement(node)) return;
+
+      switch (node.name) {
+        case "CodeGroup":
+          processCodeGroup(node);
+          break;
+        case "Tabs":
+          processTabs(node);
+          break;
+      }
+    });
+  };
+}