portosaurus 2.0.2 → 2.1.0

package/src/{core/build-utils → utils/build}/generateFavicon.mjs

@@ -6,6 +6,7 @@ import { downloadImage } from "./imageDownloader.mjs";
 import { reshapeImage } from "./imageProcessor.mjs";
 import { getCssVar } from "./cssUtils.mjs";
 import { extractSvg } from "./iconExtractor.mjs";
+import { logger } from "../logger.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -40,7 +41,7 @@ function processManifest(manifestFile, outputDir, appVersion) {
     );
     return true;
   } catch (err) {
-    console.error("[ERROR] Failed to process manifest:", err.message);
+    logger.error(`Failed to process manifest: ${err.message}`);
     fs.writeFileSync(
       path.join(outputDir, manifestFile.name),
       manifestFile.contents,
@@ -50,7 +51,7 @@ function processManifest(manifestFile, outputDir, appVersion) {
 }
 
 export async function generateFavicons(context, options = {}) {
-  console.log("\n[INFO] Generating favicons...");
+  logger.info("Generating favicons...");
 
   const { siteConfig } = context;
   const profilePicUrl =
@@ -62,14 +63,42 @@ export async function generateFavicons(context, options = {}) {
 
   const staticBaseDir = path.resolve(context.siteDir, "static");
   const imgDir = path.join(staticBaseDir, "img", "svg");
-  const imgStaticPath = "/img/svg";
   const outputDir = path.join(staticBaseDir, options.outputPath || "favicon");
 
+  // --- Smart Caching ---
+  const configHash = Buffer.from(
+    JSON.stringify({
+      profilePicUrl,
+      shape,
+      circular,
+      outputPath: options.outputPath,
+    }),
+  ).toString("base64");
+
+  const hashFilePath = path.join(outputDir, ".favicon.hash");
+
+  if (fs.existsSync(hashFilePath)) {
+    const existingHash = fs.readFileSync(hashFilePath, "utf-8");
+
+    if (existingHash === configHash) {
+      // Check if critical files actually exist
+      if (fs.existsSync(path.join(outputDir, "favicon.ico"))) {
+        logger.success("Favicons are up to date, skipping generation.");
+        return true;
+      }
+    }
+  }
+  // ---------------------
+
   // Use a consolidated cache directory inside .docusaurus
-  const cacheDir = path.join(context.siteDir, ".docusaurus", "portosaurus", "cache");
+  const cacheDir = path.join(
+    context.siteDir,
+    ".docusaurus",
+    "portosaurus",
+    "cache",
+  );
   createDirectoryIfNotExists(cacheDir);
 
-  const tempProfilePic = path.join(cacheDir, "profile_pic_src.png");
   const reshapedImagePath = path.join(cacheDir, "profile_pic_reshaped.png");
 
   const tempFiles = [];
@@ -113,12 +142,12 @@ export async function generateFavicons(context, options = {}) {
       },
     };
 
-    // 1. Download image with proxy support
+    // 1. Download image with proxy support + caching
     const downloadedRes = await downloadImage(
       profilePicUrl,
       cacheDir,
       "profile_pic_src.png",
-      { proxies }
+      { proxies, cacheDir: path.join(cacheDir, "downloads") },
     );
     tempFiles.push(downloadedRes);
 
@@ -135,7 +164,7 @@ export async function generateFavicons(context, options = {}) {
 
     createDirectoryIfNotExists(outputDir);
 
-    console.log(`[INFO] Generating favicon assets from ${finalImagePath}`);
+    logger.info(`Generating favicon assets from ${finalImagePath}`);
     const response = await favicons(finalImagePath, configuration);
 
     let imageCount = 0,
@@ -159,15 +188,18 @@ export async function generateFavicons(context, options = {}) {
       }
     }
 
-    console.log(
-      `[SUCCESS] Generated ${imageCount} favicon images and ${fileCount} support files\n`,
+    logger.success(
+      `Generated ${imageCount} favicon images and ${fileCount} support files`,
     );
-    
+
+    // Write the hash file to enable smart caching next time
+    fs.writeFileSync(hashFilePath, configHash, "utf-8");
+
     // Cleanup temporary files
     tempFiles.forEach(cleanupFile);
     return true;
   } catch (error) {
-    console.warn(`[WARNING] Favicon generation skipped: ${error.message}`);
+    logger.warn(`Favicon generation skipped: ${error.message}`);
     tempFiles.forEach(cleanupFile);
     // Don't throw - allow the build to continue
     return false;

package/src/{core/build-utils → utils/build}/generateRobotsTxt.mjs

@@ -1,5 +1,6 @@
 import fs from "fs";
 import path from "path";
+import { logger } from "../logger.mjs";
 
 /**
  * Generates a robots.txt file in the site's static directory.
@@ -12,7 +13,7 @@ export function generateRobotsTxt(context) {
     return;
   }
 
-  console.log("[INFO] Generating robots.txt...");
+  logger.info("Generating robots.txt...");
 
   const staticDir = path.resolve(context.siteDir, "static");
   const robotsPath = path.join(staticDir, "robots.txt");
@@ -46,7 +47,7 @@ export function generateRobotsTxt(context) {
 
   fs.mkdirSync(staticDir, { recursive: true });
   fs.writeFileSync(robotsPath, content);
-  console.log(`[SUCCESS] Generated robots.txt at ${robotsPath}`);
+  logger.success(`Generated robots.txt at ${robotsPath}`);
 }
 
 export default function robotsTxtPlugin(context, options) {
@@ -56,4 +57,4 @@ export default function robotsTxtPlugin(context, options) {
       generateRobotsTxt(context);
     },
   };
-}
+}

package/src/{core/build-utils → utils/build}/iconExtractor.mjs

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
+import { logger } from "../logger.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -8,11 +9,14 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  * Extracts specific SVGs from the internal assets and saves them to the project.
  */
 export async function extractSvg(iconName, destDir, options = {}) {
-  const srcPath = path.resolve(__dirname, `../../assets/img/svg/icon-${iconName}.svg`);
+  const srcPath = path.resolve(
+    __dirname,
+    `../../assets/img/svg/icon-${iconName}.svg`,
+  );
   const destPath = path.join(destDir, `icon-${iconName}.svg`);
 
   if (!fs.existsSync(srcPath)) {
-    console.warn(`[WARNING] Source icon not found: ${srcPath}`);
+    logger.warn(`Source icon not found: ${srcPath}`);
     return false;
   }
 
@@ -26,6 +30,6 @@ export async function extractSvg(iconName, destDir, options = {}) {
   }
 
   fs.writeFileSync(destPath, content);
-  console.log(`[INFO] Generated SVG icon: ${destPath}`);
+  logger.info(`Generated SVG icon: ${destPath}`);
   return destPath;
 }

package/src/utils/build/imageDownloader.mjs

@@ -0,0 +1,159 @@
+import fs from "fs";
+import path from "path";
+import https from "https";
+import http from "http";
+import crypto from "crypto";
+import { logger } from "../logger.mjs";
+
+/**
+ * Generates a short hash from a URL for use as a cache key.
+ */
+function getCacheKey(url) {
+  return crypto.createHash("md5").update(url).digest("hex");
+}
+
+/**
+ * Downloads an image from a URL and saves it to a local file.
+ * Handles redirects (up to 5 levels), falls back to proxies if needed,
+ * and supports URL-hash-based caching to avoid redundant downloads.
+ *
+ * @param {string} url       - The URL to download from.
+ * @param {string} destDir   - Directory to save the downloaded file.
+ * @param {string} fileName  - Name for the downloaded file.
+ * @param {Object} options   - Additional options.
+ * @param {string[]} options.proxies       - List of CORS proxy URLs.
+ * @param {number}   options.redirectCount - Internal redirect counter.
+ * @param {string}   options.cacheDir      - Directory for caching downloads.
+ * @param {number}   options.cacheTTL      - Cache time-to-live in ms (default: 24h).
+ */
+export async function downloadImage(url, destDir, fileName, options = {}) {
+  const {
+    proxies = [],
+    redirectCount = 0,
+    cacheDir,
+    cacheTTL = 43200000, // 6 hours
+  } = options;
+
+  if (redirectCount > 5) {
+    throw new Error("Too many redirects");
+  }
+
+  const destPath = path.join(destDir, fileName);
+  fs.mkdirSync(destDir, { recursive: true });
+
+  // ─── Cache Check ───────────────────────────────────────────
+  const forceDownload = process.env.PORTO_FORCE_DOWNLOAD === "1";
+
+  if (cacheDir && !forceDownload) {
+    const cacheKey = getCacheKey(url);
+    const cachedPath = path.join(cacheDir, `${cacheKey}-${fileName}`);
+
+    if (fs.existsSync(cachedPath)) {
+      const stats = fs.statSync(cachedPath);
+      const age = Date.now() - stats.mtimeMs;
+
+      if (age < cacheTTL) {
+        logger.info(`Using cached image (${Math.round(age / 60000)}m old)`);
+        fs.copyFileSync(cachedPath, destPath);
+        return destPath;
+      }
+    }
+  }
+
+  // ─── Download ──────────────────────────────────────────────
+  return new Promise((resolve, reject) => {
+    const protocol = url.startsWith("https") ? https : http;
+
+    protocol
+      .get(url, (response) => {
+        // Handle redirects
+        if (
+          [301, 302, 303, 307, 308].includes(response.statusCode) &&
+          response.headers.location
+        ) {
+          const redirectUrl = new URL(
+            response.headers.location,
+            url,
+          ).toString();
+          logger.info(
+            `Following redirect (${response.statusCode}) to: ${redirectUrl}`,
+          );
+          resolve(
+            downloadImage(redirectUrl, destDir, fileName, {
+              ...options,
+              redirectCount: redirectCount + 1,
+            }),
+          );
+          return;
+        }
+
+        // Handle errors and non-image content
+        if (response.statusCode !== 200) {
+          tryProxyFallback();
+          return;
+        }
+
+        const contentType = response.headers["content-type"] || "";
+        if (!contentType.startsWith("image/") && !url.includes("raw=true")) {
+          logger.warn(`Expected image but got ${contentType} from ${url}`);
+          tryProxyFallback();
+          return;
+        }
+
+        const file = fs.createWriteStream(destPath);
+        response.pipe(file);
+
+        file.on("finish", () => {
+          file.close((err) => {
+            if (err) {
+              reject(err);
+              return;
+            }
+
+            // Write to cache after successful download
+            if (cacheDir) {
+              try {
+                const cacheKey = getCacheKey(url);
+                const cachedPath = path.join(
+                  cacheDir,
+                  `${cacheKey}-${fileName}`,
+                );
+                fs.mkdirSync(cacheDir, { recursive: true });
+                fs.copyFileSync(destPath, cachedPath);
+              } catch {
+                // Cache write failure is non-fatal
+              }
+            }
+
+            resolve(destPath);
+          });
+        });
+
+        file.on("error", (err) => {
+          fs.unlink(destPath, () => reject(err));
+        });
+      })
+      .on("error", (err) => {
+        tryProxyFallback(err);
+      });
+
+    function tryProxyFallback(originalError) {
+      if (proxies.length > 0) {
+        const nextProxy = proxies[0];
+        const remainingProxies = proxies.slice(1);
+        const proxyUrl = `${nextProxy}${encodeURIComponent(url)}`;
+        logger.info(
+          `Download failed or invalid content. Retrying via proxy: ${nextProxy}`,
+        );
+        resolve(
+          downloadImage(proxyUrl, destDir, fileName, {
+            ...options,
+            proxies: remainingProxies,
+          }),
+        );
+      } else {
+        reject(originalError || new Error(`Failed to download image: ${url}`));
+      }
+    }
+  });
+}

package/src/{core/build-utils → utils/build}/imageProcessor.mjs

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import sharp from "sharp";
+import { logger } from "../logger.mjs";
 
 /**
  * Reshapes an image into a circle or square with rounded corners.
@@ -19,7 +20,7 @@ export async function reshapeImage(inputPath, outputPath, shape = "circle") {
 
     const image = sharp(inputPath);
     const metadata = await image.metadata();
-    
+
     if (!metadata.width || !metadata.height) {
       throw new Error("Could not extract image metadata (width/height)");
     }
@@ -38,18 +39,16 @@ export async function reshapeImage(inputPath, outputPath, shape = "circle") {
       // Create circular mask
       const radius = size / 2;
       const circleSvg = Buffer.from(
-        `<svg><circle cx="${radius}" cy="${radius}" r="${radius}" /></svg>`
+        `<svg><circle cx="${radius}" cy="${radius}" r="${radius}" /></svg>`,
       );
 
-      pipeline = pipeline.composite([
-        { input: circleSvg, blend: "dest-in" }
-      ]);
+      pipeline = pipeline.composite([{ input: circleSvg, blend: "dest-in" }]);
     }
 
     await pipeline.png().toFile(outputPath);
     return outputPath;
   } catch (err) {
-    console.error(`[ERROR] Image processing failed: ${err.message}`);
+    logger.error(`Image processing failed: ${err.message}`);
     throw err;
   }
 }

package/src/utils/helpers.mjs

@@ -0,0 +1,153 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { spawn } from "child_process";
+import { logger } from "./logger.mjs";
+import { getDocuCmd } from "./packageManager.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const PortoRoot = path.resolve(__dirname, "../..");
+
+/**
+ * Write the ephemeral .portosaurus/docusaurus.config.mjs shim.
+ */
+export function writePortoConfigShim(UserRoot) {
+  const dotDir = path.join(UserRoot, ".docusaurus", "portosaurus");
+  fs.mkdirSync(dotDir, { recursive: true });
+
+  const configJsAbsolute = path.join(UserRoot, "config.js").replace(/\\/g, "/");
+  const createDocuConfAbsolute = path
+    .resolve(PortoRoot, "src/core/buildDocuConfig.mjs")
+    .replace(/\\/g, "/");
+
+  const shimContent = `// Auto-generated by Portosaurus CLI — do not edit
+/** @type {import('@docusaurus/types').Config} */
+export default async function getConfig() {
+  const { buildDocuConfig } = await import("file://${createDocuConfAbsolute}");
+  const { usrConf } = await import("file://${configJsAbsolute}");
+  return buildDocuConfig(usrConf, "${UserRoot.replace(/\\/g, "/")}");
+}
+`;
+
+  const shimPath = path.join(dotDir, "docusaurus.config.js");
+  fs.writeFileSync(shimPath, shimContent);
+  logger.debug(`Config shim written to ${shimPath}`);
+
+  return shimPath;
+}
+
+/**
+ * Validate that the current directory is a Portosaurus project.
+ */
+export function validateProject(UserRoot) {
+  const configPath = path.join(UserRoot, "config.js");
+  if (!fs.existsSync(configPath)) {
+    logger.log("");
+    logger.error(
+      "config.js not found. Are you in a Portosaurus project directory?",
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * Ensure essential user content directories exist.
+ */
+export function ensureContentDirs(UserRoot) {
+  for (const dir of ["notes", "blog", "static"]) {
+    fs.mkdirSync(path.join(UserRoot, dir), { recursive: true });
+  }
+
+  const notesIndex = path.join(UserRoot, "notes", "index.mdx");
+  if (!fs.existsSync(notesIndex)) {
+    fs.writeFileSync(
+      notesIndex,
+      `---\nhide_table_of_contents: true\n---\n\nimport NoteCards from "portosaurus/src/theme/components/NoteIndex/index.js";\n\n# Notes\n\n<NoteCards />\n`,
+    );
+    logger.debug("Created default notes/index.mdx");
+  }
+}
+
+/**
+ * Spawn a Docusaurus command and wait for it to complete.
+ */
+export function runDocusaurus(command, extraArgs, UserRoot, configPath) {
+  const {
+    command: cmd,
+    args: pmArgs,
+    packageManager,
+  } = getDocuCmd(UserRoot);
+
+  logger.info(`Running docusaurus ${command} (via ${packageManager})`);
+
+  const finalArgs = [
+    ...pmArgs,
+    command,
+    UserRoot,
+    "--config",
+    configPath,
+    ...extraArgs,
+  ];
+
+  const child = spawn(cmd, finalArgs, {
+    stdio: "inherit",
+    cwd: UserRoot,
+    env: { ...process.env, FORCE_COLOR: "true" },
+  });
+
+  return new Promise((resolve, reject) => {
+    child.on("error", (err) => {
+      logger.error(`Failed to run docusaurus ${command}: ${err.message}`);
+      reject(err);
+    });
+    child.on("close", (code) => {
+      if (code === 0) resolve();
+      else process.exit(code);
+    });
+  });
+}
+
+// Recursively copy a directory and apply text replacements.
+export function mirrorSync(src, dest, replacements = {}, ignores = []) {
+  const ignoreSet = new Set(ignores);
+  const textExtensions = new Set([
+    ".js",
+    ".mjs",
+    ".json",
+    ".md",
+    ".mdx",
+    ".yml",
+    ".yaml",
+    ".css",
+    ".html",
+    ".txt",
+  ]);
+
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (ignoreSet.has(entry.name)) continue;
+
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      mirrorSync(srcPath, destPath, replacements, ignores);
+    } else {
+      const ext = path.extname(entry.name).toLowerCase();
+
+      // If replacements exist and it's a known text file, process it
+      if (Object.keys(replacements).length > 0 && textExtensions.has(ext)) {
+        let content = fs.readFileSync(srcPath, "utf8");
+        for (const [key, value] of Object.entries(replacements)) {
+          // Replace all occurrences of {{key}}
+          const regex = new RegExp(`\\{\\{${key}\\}\\}`, "g");
+          content = content.replace(regex, value);
+        }
+        fs.writeFileSync(destPath, content);
+      } else {
+        fs.copyFileSync(srcPath, destPath); // Safe copy for binaries (images, etc) or when no replacements needed
+      }
+    }
+  }
+}

package/src/utils/logger.mjs

@@ -0,0 +1,53 @@
+import { createConsola } from "consola";
+import chalk from "chalk";
+
+/**
+ * Logger
+ * Mimics the official Docusaurus CLI style for a familiar DX.
+ */
+
+const consola = createConsola({
+  level: process.env.DEBUG || process.env.VERBOSE ? 4 : 3,
+});
+
+const format = (badge, color, ...args) => {
+  const prefix = color.bold(badge.padEnd(10));
+  const message = args
+    .map((arg) => (typeof arg === "string" ? arg : JSON.stringify(arg)))
+    .join(" ");
+
+  message.split("\n").forEach((line) => {
+    console.log(`${prefix} ${line}`);
+  });
+};
+
+export const logger = {
+  log: (...args) => console.log(...args),
+  info: (...args) => format("[INFO]", chalk.cyan, ...args),
+  success: (...args) => format("[SUCCESS]", chalk.green, ...args),
+  warn: (...args) => format("[WARNING]", chalk.yellow, ...args),
+  error: (...args) => format("[ERROR]", chalk.red, ...args),
+  tip: (...args) => format("[TIP]", chalk.magenta, ...args),
+
+  debug: (...args) => {
+    if (process.env.DEBUG || process.env.VERBOSE) {
+      format("[DEBUG]", chalk.gray, ...args);
+    }
+  },
+
+  box: (msg, title = "Portosaurus") => {
+    consola.box({
+      message: msg,
+      title: chalk.magenta.bold(title),
+      style: {
+        borderColor: "magenta",
+        borderStyle: "rounded",
+      },
+    });
+  },
+
+  start: (msg) => consola.start(msg),
+  ready: (msg) => consola.ready(msg),
+};
+
+export default logger;

package/src/utils/packageManager.mjs

@@ -0,0 +1,88 @@
+/**
+ * Package manager detection and CLI utility (ESM)
+ */
+import fs from "fs";
+import path from "path";
+
+/**
+ * Returns a package manager object for the given directory.
+ */
+export function getPackageManager(dir) {
+  let name = null;
+
+  // Detect by lockfile
+  if (
+    fs.existsSync(path.join(dir, "bun.lock")) ||
+    fs.existsSync(path.join(dir, "bun.lockb"))
+  ) {
+    name = "bun";
+  } else if (fs.existsSync(path.join(dir, "pnpm-lock.yaml"))) {
+    name = "pnpm";
+  } else if (fs.existsSync(path.join(dir, "yarn.lock"))) {
+    name = "yarn";
+  } else if (fs.existsSync(path.join(dir, "package-lock.json"))) {
+    name = "npm";
+  }
+
+  // Detect by environment
+  else if (process.env.npm_config_user_agent) {
+    if (process.env.npm_config_user_agent.includes("bun")) name = "bun";
+    else if (process.env.npm_config_user_agent.includes("pnpm")) name = "pnpm";
+    else if (process.env.npm_config_user_agent.includes("yarn")) name = "yarn";
+    else if (process.env.npm_config_user_agent.includes("npm")) name = "npm";
+  }
+
+  // Detect by runtime
+  else if (typeof process !== "undefined" && process.versions?.bun) {
+    name = "bun";
+  }
+
+  if (!name) {
+    throw new Error(
+      "Supported package manager (bun, pnpm, yarn, or npm) not detected.",
+    );
+  }
+
+  const exec = {
+    npm: "npx",
+    bun: "bunx",
+    pnpm: "pnpm dlx",
+    yarn: "yarn dlx",
+  }[name];
+
+  return {
+    name,
+    install: `${name} install`,
+    run: `${name} run`,
+    exec,
+  };
+}
+
+/**
+ * Resolves the command to run Docusaurus based on the package manager and project state.
+ */
+export function getDocuCmd(UserRoot) {
+  const pm = getPackageManager(UserRoot);
+
+  // Check for node_modules/.bin/docusaurus
+  const localDocusaurus = path.join(
+    UserRoot,
+    "node_modules",
+    ".bin",
+    "docusaurus",
+  );
+
+  if (fs.existsSync(localDocusaurus)) {
+    const local = {
+      bun: { command: "bun", args: ["docusaurus"] },
+      npm: { command: "npm", args: ["run", "docusaurus", "--"] },
+      pnpm: { command: "pnpm", args: ["docusaurus"] },
+      yarn: { command: "yarn", args: ["docusaurus"] },
+    }[pm.name];
+
+    return { ...local, packageManager: pm.name };
+  }
+
+  // Fallback to npx/bunx if not found locally
+  return { command: pm.exec, args: ["docusaurus"], packageManager: pm.name };
+}

package/src/components/Preview/index.js

@@ -1,3 +0,0 @@
-export { PreviewProvider, usePreview } from './state/index.js';
-export { default as ViewerWindow } from './components/ViewerWindow.js';
-export { Pv, SrcPv } from './components/Triggers/index.js';