radiant-docs 0.1.0

package/dist/index.js

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { spawn, execSync } from "child_process";
+import path from "path";
+import fs from "fs-extra";
+import chokidar from "chokidar";
+import { fileURLToPath } from "url";
+import envPaths from "env-paths";
+import crypto from "crypto";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+var paths = envPaths("radiant", { suffix: "" });
+var VERSION = "0.1.0";
+var lastErrorMessage = "";
+var lastErrorTime = 0;
+var ERROR_DEDUPE_MS = 2e3;
+var colors = {
+  reset: "\x1B[0m",
+  bright: "\x1B[1m",
+  dim: "\x1B[2m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  cyan: "\x1B[36m",
+  magenta: "\x1B[35m"
+};
+var log = {
+  info: (msg) => console.log(`${colors.cyan}\u25CF${colors.reset} ${msg}`),
+  success: (msg) => console.log(`${colors.green}\u2713${colors.reset} ${msg}`),
+  error: (msg) => console.log(`${colors.red}\u2717${colors.reset} ${msg}`),
+  warn: (msg) => console.log(`${colors.yellow}\u26A0${colors.reset} ${msg}`),
+  file: (msg) => console.log(
+    `${colors.dim}\u21BB${colors.reset} ${colors.dim}${msg}${colors.reset}`
+  ),
+  blank: () => console.log("")
+};
+function getUserDocsDir() {
+  return process.cwd();
+}
+function getProjectHash(docsDir) {
+  return crypto.createHash("md5").update(docsDir).digest("hex").slice(0, 8);
+}
+function getCacheDir(docsDir) {
+  const projectHash = getProjectHash(docsDir);
+  return path.join(paths.cache, projectHash);
+}
+function getTemplateDir() {
+  return path.join(__dirname, "../template");
+}
+function getContentDir(cacheDir) {
+  return path.join(cacheDir, "src/content/docs");
+}
+async function validateUserDocs(docsDir) {
+  const docsJsonPath = path.join(docsDir, "docs.json");
+  if (!fs.existsSync(docsJsonPath)) {
+    log.error("No docs.json found in current directory.");
+    log.info("Run this command from your documentation root folder.");
+    log.blank();
+    log.info(`Expected location: ${colors.dim}${docsJsonPath}${colors.reset}`);
+    process.exit(1);
+  }
+  try {
+    const content = await fs.readFile(docsJsonPath, "utf-8");
+    JSON.parse(content);
+  } catch {
+    log.error("Invalid JSON in docs.json");
+    process.exit(1);
+  }
+}
+async function setupCache(cacheDir) {
+  const templateDir = getTemplateDir();
+  const nodeModulesExists = fs.existsSync(path.join(cacheDir, "node_modules"));
+  const cacheExists = fs.existsSync(cacheDir);
+  if (!fs.existsSync(templateDir)) {
+    log.error(
+      "Framework template not found. The CLI package may be corrupted."
+    );
+    log.info(`Expected at: ${templateDir}`);
+    process.exit(1);
+  }
+  let needsUpdate = !cacheExists;
+  if (cacheExists) {
+    try {
+      const templatePkg = await fs.readJson(
+        path.join(templateDir, "package.json")
+      );
+      const cachePkg = await fs.readJson(path.join(cacheDir, "package.json"));
+      if (templatePkg.version !== cachePkg.version) {
+        needsUpdate = true;
+        log.info("Framework update detected, refreshing cache...");
+      }
+    } catch {
+      needsUpdate = true;
+    }
+  }
+  if (needsUpdate) {
+    log.info("Setting up Radiant framework...");
+    if (cacheExists) {
+      await fs.remove(cacheDir);
+    }
+    await fs.copy(templateDir, cacheDir, {
+      filter: (src) => !src.includes("node_modules")
+    });
+    log.success("Framework copied to cache.");
+    return true;
+  }
+  return !nodeModulesExists;
+}
+async function installDependencies(cacheDir) {
+  log.info("Installing dependencies (first run only)...");
+  try {
+    execSync("npm install --silent --no-fund --no-audit", {
+      cwd: cacheDir,
+      stdio: "pipe"
+    });
+    log.success("Dependencies installed.");
+  } catch (error) {
+    log.error("Failed to install dependencies.");
+    throw error;
+  }
+}
+async function syncContent(docsDir, contentDir) {
+  await fs.emptyDir(contentDir);
+  await fs.copy(docsDir, contentDir, {
+    filter: (src) => {
+      const basename = path.basename(src);
+      const relativePath = path.relative(docsDir, src);
+      if (basename.startsWith(".")) return false;
+      if (relativePath.includes("node_modules")) return false;
+      if (basename === "package.json" || basename === "package-lock.json")
+        return false;
+      if (basename.toLowerCase().startsWith("readme")) return false;
+      return true;
+    }
+  });
+}
+async function runAstroSync(cacheDir) {
+  try {
+    execSync("npx astro sync", {
+      cwd: cacheDir,
+      stdio: "pipe"
+    });
+  } catch {
+  }
+}
+function startDevServer(cacheDir) {
+  const child = spawn("npm", ["run", "dev"], {
+    cwd: cacheDir,
+    shell: true,
+    env: {
+      ...process.env,
+      FORCE_COLOR: "1"
+    }
+  });
+  let serverStarted = false;
+  let serverUrl = "http://localhost:4321";
+  const processOutput = (data, isError = false) => {
+    const output = data.toString();
+    const lines = output.split("\n");
+    for (const line of lines) {
+      const trimmedLine = line.trim();
+      if (!trimmedLine) continue;
+      const urlMatch = line.match(/http:\/\/localhost:\d+/);
+      if (urlMatch) {
+        serverUrl = urlMatch[0];
+      }
+      if (!serverStarted && (line.includes("watching for file changes") || line.includes("Local") && line.includes("localhost"))) {
+        serverStarted = true;
+        log.blank();
+        log.success("Dev server ready!");
+        console.log(`   ${colors.bright}Local:${colors.reset}   ${serverUrl}`);
+        log.blank();
+        log.info("Watching for changes...");
+        log.blank();
+        continue;
+      }
+      if (line.includes("[USER_ERROR]")) {
+        const errorMsg = line.split("[USER_ERROR]:")[1]?.trim() || line;
+        const now = Date.now();
+        if (errorMsg === lastErrorMessage && now - lastErrorTime < ERROR_DEDUPE_MS) {
+          continue;
+        }
+        lastErrorMessage = errorMsg;
+        lastErrorTime = now;
+        log.blank();
+        log.error(errorMsg);
+        log.blank();
+        continue;
+      }
+    }
+  };
+  child.stdout?.on("data", (data) => processOutput(data, false));
+  child.stderr?.on("data", (data) => processOutput(data, true));
+  child.on("exit", (code) => {
+    if (code !== 0 && code !== null) {
+      log.blank();
+      log.error(`Dev server exited with code ${code}`);
+      process.exit(code);
+    }
+  });
+  return child;
+}
+function watchUserContent(docsDir, contentDir, _onSync) {
+  const watcher = chokidar.watch(docsDir, {
+    ignored: [
+      "**/node_modules/**",
+      "**/.git/**",
+      "**/package.json",
+      "**/package-lock.json",
+      /^\./
+    ],
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 100,
+      pollInterval: 50
+    }
+  });
+  let debounceTimer = null;
+  const pendingChanges = /* @__PURE__ */ new Set();
+  const processChanges = async () => {
+    if (pendingChanges.size === 0) return;
+    for (const filepath of pendingChanges) {
+      const relativePath = path.relative(docsDir, filepath);
+      log.file(relativePath);
+    }
+    try {
+      await syncContent(docsDir, contentDir);
+      await _onSync();
+    } catch (error) {
+      log.error(`Sync failed: ${error}`);
+    }
+    pendingChanges.clear();
+  };
+  watcher.on("all", (event, filepath) => {
+    if (event === "change" || event === "add" || event === "unlink") {
+      pendingChanges.add(filepath);
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(processChanges, 300);
+    }
+  });
+  return watcher;
+}
+function showHelp() {
+  console.log(`
+${colors.bright}${colors.cyan}\u25C6 Radiant${colors.reset} v${VERSION}
+
+${colors.bright}Usage:${colors.reset}
+  radiant              Start the dev server
+  radiant dev          Start the dev server
+  radiant --help       Show this help message
+  radiant --version    Show version
+
+${colors.bright}Description:${colors.reset}
+  Run this command from your documentation folder (containing docs.json)
+  to preview your docs locally with hot reload.
+`);
+}
+async function run() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    showHelp();
+    process.exit(0);
+  }
+  if (args.includes("--version") || args.includes("-v")) {
+    console.log(VERSION);
+    process.exit(0);
+  }
+  const command = args[0];
+  if (command && command !== "dev") {
+    log.error(`Unknown command: ${command}`);
+    showHelp();
+    process.exit(1);
+  }
+  log.blank();
+  console.log(
+    `${colors.bright}${colors.cyan}\u25C6 Radiant${colors.reset} ${colors.dim}v${VERSION}${colors.reset}`
+  );
+  log.blank();
+  const docsDir = getUserDocsDir();
+  const cacheDir = getCacheDir(docsDir);
+  const contentDir = getContentDir(cacheDir);
+  await validateUserDocs(docsDir);
+  const needsInstall = await setupCache(cacheDir);
+  if (needsInstall) {
+    await installDependencies(cacheDir);
+  }
+  log.info("Syncing your documentation...");
+  await syncContent(docsDir, contentDir);
+  await runAstroSync(cacheDir);
+  log.success("Content synced.");
+  log.info("Starting dev server...");
+  const devServer = startDevServer(cacheDir);
+  const watcher = watchUserContent(docsDir, contentDir, async () => {
+    await runAstroSync(cacheDir);
+  });
+  const cleanup = () => {
+    log.blank();
+    log.info("Shutting down...");
+    watcher.close();
+    devServer.kill();
+    process.exit(0);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+run().catch((error) => {
+  log.error(error.message || String(error));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "radiant-docs",
+  "version": "0.1.0",
+  "description": "CLI tool for previewing Radiant documentation locally",
+  "type": "module",
+  "bin": {
+    "radiant": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "prepublishOnly": "npm run build && npm run bundle-template",
+    "bundle-template": "node scripts/bundle-template.js"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "env-paths": "^3.0.0",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "keywords": [
+    "documentation",
+    "docs",
+    "cli",
+    "radiant",
+    "astro"
+  ],
+  "license": "MIT"
+}

package/template/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

package/template/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

package/template/astro.config.mjs

@@ -0,0 +1,216 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+import tailwindcss from "@tailwindcss/vite";
+import mdx from "@astrojs/mdx";
+import alpine from "@astrojs/alpinejs";
+import icon from "astro-icon";
+import expressiveCode from "astro-expressive-code";
+import fs from "fs";
+import path from "path";
+import { getConfig, validateMdxContent } from "./src/lib/validation";
+
+if (process.env.npm_lifecycle_event === "build") {
+  // Run validation for build before Astro's internal validation
+  try {
+    await getConfig();
+    await validateMdxContent();
+  } catch (error) {
+    console.error(error); // Log our [USER_ERROR] message
+    process.exit(1);
+  }
+}
+
+// Recursively copy all image files from src/content/docs to public
+// This runs in both dev and prod to ensure user assets are always available
+function copyContentAssets() {
+  const CWD = process.cwd();
+  const DOCS_DIR = path.join(CWD, "src/content/docs");
+  const PUBLIC_DIR = path.join(CWD, "public");
+
+  const imageExtensions = [
+    ".svg",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".gif",
+    ".avif",
+    ".ico",
+  ];
+
+  function shouldCopyFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return imageExtensions.includes(ext);
+  }
+
+  // Build a set of all image file paths in src/content/docs
+  function collectImagePaths(dir, baseDir, pathSet) {
+    if (!fs.existsSync(dir)) return;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const entryPath = path.join(dir, entry.name);
+
+      // Skip certain files/directories
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+
+      if (entry.isDirectory()) {
+        collectImagePaths(entryPath, baseDir, pathSet);
+      } else if (entry.isFile() && shouldCopyFile(entryPath)) {
+        // Store relative path from baseDir
+        const relativePath = path.relative(baseDir, entryPath);
+        pathSet.add(relativePath.replace(/\\/g, "/")); // Normalize path separators
+      }
+    }
+  }
+
+  // Single-pass copy: returns true if any files were copied (or subdirectories contain files)
+  function copyDirectory(srcDir, destDir) {
+    if (!fs.existsSync(srcDir)) return false;
+
+    const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+    let hasCopiedFiles = false;
+
+    for (const entry of entries) {
+      const srcPath = path.join(srcDir, entry.name);
+      const destPath = path.join(destDir, entry.name);
+
+      // Skip certain files/directories
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+
+      if (entry.isDirectory()) {
+        // Recursively copy subdirectory - only create if it contains images
+        const subDirHasFiles = copyDirectory(srcPath, destPath);
+        if (subDirHasFiles) {
+          hasCopiedFiles = true;
+          // Create directory only if we actually copied something into it
+          if (!fs.existsSync(destPath)) {
+            fs.mkdirSync(destPath, { recursive: true });
+          }
+        }
+      } else if (entry.isFile() && shouldCopyFile(srcPath)) {
+        // Ensure destination directory exists before copying
+        if (!fs.existsSync(destDir)) {
+          fs.mkdirSync(destDir, { recursive: true });
+        }
+        fs.copyFileSync(srcPath, destPath);
+        hasCopiedFiles = true;
+      }
+    }
+
+    return hasCopiedFiles;
+  }
+
+  // Delete files in public that don't exist in the source set
+  function deleteOrphanedFiles(publicDir, baseDir, validPaths) {
+    if (!fs.existsSync(publicDir)) return;
+
+    const entries = fs.readdirSync(publicDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const entryPath = path.join(publicDir, entry.name);
+      const relativePath = path
+        .relative(baseDir, entryPath)
+        .replace(/\\/g, "/");
+
+      if (entry.isDirectory()) {
+        // Recursively check subdirectories
+        deleteOrphanedFiles(entryPath, baseDir, validPaths);
+      } else if (entry.isFile() && shouldCopyFile(entryPath)) {
+        // Delete if not in valid paths set
+        if (!validPaths.has(relativePath)) {
+          fs.unlinkSync(entryPath);
+        }
+      }
+    }
+  }
+
+  function cleanupEmptyDirs(dir, baseDir) {
+    if (!fs.existsSync(dir)) return;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const entryPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        cleanupEmptyDirs(entryPath, baseDir);
+      }
+    }
+
+    // After processing children, check if this directory is empty
+    const remainingEntries = fs.readdirSync(dir);
+    if (remainingEntries.length === 0 && dir !== baseDir) {
+      fs.rmdirSync(dir);
+    }
+  }
+
+  // Main sync function
+  function syncAssets() {
+    if (!fs.existsSync(DOCS_DIR)) return;
+
+    // Step 1: Collect all valid image paths from source
+    const validImagePaths = new Set();
+    collectImagePaths(DOCS_DIR, DOCS_DIR, validImagePaths);
+
+    // Step 2: Copy all images from source to public
+    copyDirectory(DOCS_DIR, PUBLIC_DIR);
+
+    // Step 3: Delete orphaned files in public
+    deleteOrphanedFiles(PUBLIC_DIR, PUBLIC_DIR, validImagePaths);
+
+    // Step 4: Clean up empty directories
+    cleanupEmptyDirs(PUBLIC_DIR, PUBLIC_DIR);
+  }
+
+  return {
+    name: "copy-content-assets",
+    buildStart() {
+      // Always copy in both dev and prod
+      try {
+        if (fs.existsSync(DOCS_DIR)) {
+          syncAssets();
+          console.log("✅ Copied content assets to public folder");
+        }
+      } catch (error) {
+        console.warn("Failed to copy content assets:", error);
+      }
+    },
+    // Also watch for changes in dev mode
+    configureServer(server) {
+      const watcher = server.watcher;
+      watcher.on("change", (file) => {
+        if (file.includes("src/content/docs") && shouldCopyFile(file)) {
+          const relativePath = path.relative(
+            path.join(CWD, "src/content/docs"),
+            file
+          );
+          const destPath = path.join(PUBLIC_DIR, relativePath);
+          const destDir = path.dirname(destPath);
+
+          if (!fs.existsSync(destDir)) {
+            fs.mkdirSync(destDir, { recursive: true });
+          }
+          fs.copyFileSync(file, destPath);
+        }
+      });
+    },
+  };
+}
+
+// https://astro.build/config
+export default defineConfig({
+  vite: {
+    plugins: [tailwindcss(), copyContentAssets()],
+  },
+  output: "static",
+  build: {
+    format: "directory",
+  },
+  integrations: [
+    expressiveCode(),
+    mdx(),
+    alpine({ entrypoint: "/src/entrypoint" }),
+    icon(),
+  ],
+});

package/template/ec.config.mjs

@@ -0,0 +1,51 @@
+import { defineEcConfig } from "astro-expressive-code";
+import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
+import { pluginCollapsibleSections } from "@expressive-code/plugin-collapsible-sections";
+import { pluginFileIcons } from "@xt0rted/expressive-code-file-icons";
+
+export default defineEcConfig({
+  themes: ["min-dark", "min-light"],
+  // Customize as needed:
+  styleOverrides: {
+    borderRadius: "12px",
+    borderColor: "var(--color-neutral-200)",
+    borderWidth: "1px",
+    codeFontSize: "13px",
+    frames: {
+      frameBoxShadowCssValue: "var(--shadow-xs)",
+      inlineButtonBorder: "var(--color-neutral-200)",
+      inlineButtonBorderOpacity: "1",
+      copyIcon: `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Crect width='14' height='14' x='8' y='8' rx='2' ry='2'/%3E%3Cpath d='M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2'/%3E%3C/svg%3E")`,
+    },
+    lineNumbers: {
+      foreground: "var(--color-neutral-400)",
+    },
+    textMarkers: {
+      markBackground: "var(--color-neutral-100)",
+    },
+    collapsibleSections: {
+      closedBackgroundColor: "var(--color-neutral-200)",
+      openBackgroundColor: "var(--color-neutral-100)",
+      openBackgroundColorCollapsible: "var(--color-neutral-100)",
+      collapseIcon: `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M12 22v-6'/%3E%3Cpath d='M12 8V2'/%3E%3Cpath d='M4 12H2'/%3E%3Cpath d='M10 12H8'/%3E%3Cpath d='M16 12h-2'/%3E%3Cpath d='M22 12h-2'/%3E%3Cpath d='m15 19-3-3-3 3'/%3E%3Cpath d='m15 5-3 3-3-3'/%3E%3C/svg%3E")`,
+      expandIcon: `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M12 22v-6'/%3E%3Cpath d='M12 8V2'/%3E%3Cpath d='M4 12H2'/%3E%3Cpath d='M10 12H8'/%3E%3Cpath d='M16 12h-2'/%3E%3Cpath d='M22 12h-2'/%3E%3Cpath d='m15 19-3 3-3-3'/%3E%3Cpath d='m15 5-3-3-3 3'/%3E%3C/svg%3E")`,
+      closedTextColor: "var(--color-neutral-500)",
+    },
+    // codeFontFamily: '"JetBrains Mono", monospace',
+  },
+
+  plugins: [
+    pluginLineNumbers(),
+    pluginCollapsibleSections(),
+    // @ts-ignore - plugin types not fully compatible
+    pluginFileIcons({
+      iconClass: "size-4",
+      titleClass: "!flex !items-center !gap-1",
+    }),
+  ],
+  defaultProps: {
+    wrap: false,
+    collapseStyle: "collapsible-auto",
+    showLineNumbers: false,
+  },
+});