create-bl-theme 1.0.2 → 1.0.4

package/README.md

@@ -34,23 +34,47 @@ The CLI will prompt you for:
 ### Validate a theme
 
 ```bash
-create-bl-theme validate [directory]
+# Validate a local directory
+create-bl-theme validate ./my-theme
+
+# Validate directly from a GitHub repository
+create-bl-theme validate https://github.com/username/theme-repo
 ```
 
-Checks that your theme has all required files and valid metadata.
+The validator checks:
+- Required files (metadata.json, style.css, images/)
+- Valid JSON structure and required fields
+- Image integrity (detects corrupted files)
+- Image dimensions (recommends 1280x720, but other sizes work fine)
 
 ## Generated Structure
 
 ```
 my-theme/
-├── metadata.json   # Theme metadata (required)
-├── style.css       # Your CSS styles (required)
-├── shader.json     # Shader config (if enabled)
-├── README.md       # Theme documentation
-└── images/         # Screenshots (required)
+├── metadata.json    # Theme metadata (required)
+├── style.css        # Your CSS styles (required)
+├── DESCRIPTION.md   # Rich description (optional, takes precedence)
+├── shader.json      # Shader config (if enabled)
+├── README.md        # Theme documentation
+└── images/          # Screenshots (required)
     └── preview.png
 ```
 
+### Theme Description Options
+
+You can provide your theme description in two ways:
+
+1. **`description` field in metadata.json** - Simple, inline description for basic themes
+2. **`DESCRIPTION.md` file** - For richer descriptions with formatting (recommended for longer descriptions)
+
+If both exist, `DESCRIPTION.md` takes precedence. At least one must be present.
+
+Better Lyrics supports **GitHub Flavored Markdown (GFM)** in DESCRIPTION.md, so you can use:
+- **Bold**, *italic*, and other text formatting
+- [Links](https://example.com) and images
+- Lists, tables, and code blocks
+- Any other GFM features
+
 ## Theme Development
 
 1. **Edit `style.css`** - Add your custom styles. Use browser DevTools to inspect Better Lyrics elements and find the right selectors.

package/bin/cli.js

@@ -4,13 +4,23 @@ import prompts from "prompts";
 import pc from "picocolors";
 import fs from "fs";
 import path from "path";
+import os from "os";
 import { fileURLToPath } from "url";
+import { imageSize } from "image-size";
+import { execSync } from "child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
 
+// Recommended image dimensions
+const RECOMMENDED_WIDTH = 1280;
+const RECOMMENDED_HEIGHT = 720;
+
+// GitHub URL patterns
+const GITHUB_URL_PATTERN = /^(?:https?:\/\/)?(?:www\.)?github\.com\/([^\/]+)\/([^\/]+)(?:\/)?(?:\.git)?$/;
+
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
@@ -35,12 +45,13 @@ async function main() {
 
 function showHelp() {
   console.log(`${pc.bold("Usage:")}
-  ${pc.cyan("create-bl-theme")} [name]        Create a new theme
-  ${pc.cyan("create-bl-theme")} validate [dir] Validate a theme directory
+  ${pc.cyan("create-bl-theme")} [name]              Create a new theme
+  ${pc.cyan("create-bl-theme")} validate [dir|url]  Validate a theme (local or GitHub)
 
 ${pc.bold("Examples:")}
   ${pc.dim("$")} create-bl-theme my-awesome-theme
   ${pc.dim("$")} create-bl-theme validate ./my-theme
+  ${pc.dim("$")} create-bl-theme validate https://github.com/user/theme-repo
 `);
 }
 
@@ -81,6 +92,12 @@ async function create(targetDir) {
       message: "Description:",
       initial: "A custom theme for Better Lyrics",
     },
+    {
+      type: "confirm",
+      name: "useDescriptionFile",
+      message: "Use DESCRIPTION.md for richer formatting? (recommended for longer descriptions)",
+      initial: false,
+    },
     {
       type: "text",
       name: "creator",
@@ -138,7 +155,6 @@ async function create(targetDir) {
   const metadata = {
     id: response.id,
     title: response.title,
-    description: response.description,
     creators: [response.creator],
     minVersion: "2.0.5.6",
     hasShaders: response.hasShaders,
@@ -147,11 +163,55 @@ async function create(targetDir) {
     images: ["preview.png"],
   };
 
+  // Only include description in metadata.json if not using DESCRIPTION.md
+  if (!response.useDescriptionFile) {
+    metadata.description = response.description;
+  }
+
   fs.writeFileSync(
     path.join(fullPath, "metadata.json"),
     JSON.stringify(metadata, null, 2)
   );
 
+  // Create DESCRIPTION.md if user opted for it
+  if (response.useDescriptionFile) {
+    const descriptionMd = `<!--
+  Better Lyrics supports GitHub Flavored Markdown (GFM) for theme descriptions.
+  You can use all standard GFM features including:
+  - **Bold** and *italic* text
+  - [Links](https://example.com)
+  - Images: ![alt text](https://example.com/image.png)
+  - Lists (ordered and unordered)
+  - Code blocks with syntax highlighting
+  - Tables
+  - And more!
+
+  This file takes precedence over the "description" field in metadata.json.
+  Delete this comment block when you're ready to publish.
+-->
+
+## Features
+
+- Add your theme features here
+- Describe what makes your theme special
+- Use **bold** for emphasis on key points
+
+## Preview
+
+<!-- You can embed images directly in your description -->
+<!-- ![Theme Preview](https://your-image-url.png) -->
+
+## Installation Notes
+
+Any special instructions for using this theme.
+
+## Compatibility
+
+- Works with Better Lyrics v2.0.5.6+
+`;
+    fs.writeFileSync(path.join(fullPath, "DESCRIPTION.md"), descriptionMd);
+  }
+
   // Create style.css from template
   const cssTemplate = fs.readFileSync(
     path.join(TEMPLATES_DIR, "style.css"),
@@ -205,12 +265,17 @@ MIT
   console.log(
     `  ${pc.dim("3.")} Add a preview screenshot to ${pc.cyan("images/preview.png")}`
   );
+  let stepNum = 4;
+  if (response.useDescriptionFile) {
+    console.log(`  ${pc.dim(`${stepNum}.`)} Edit ${pc.cyan("DESCRIPTION.md")} with your theme description`);
+    stepNum++;
+  }
   if (response.hasShaders) {
-    console.log(`  ${pc.dim("4.")} Configure ${pc.cyan("shader.json")} for shader effects`);
+    console.log(`  ${pc.dim(`${stepNum}.`)} Configure ${pc.cyan("shader.json")} for shader effects`);
+    stepNum++;
   }
-  const submitStep = response.hasShaders ? "5." : "4.";
   console.log(
-    `  ${pc.dim(submitStep)} Push to GitHub and submit to the theme store`
+    `  ${pc.dim(`${stepNum}.`)} Push to GitHub and submit to the theme store`
   );
   console.log(
     `      ${pc.dim("https://github.com/boidushya/better-lyrics-themes")}`
@@ -223,10 +288,45 @@ MIT
 }
 
 async function validate(dir) {
-  const fullPath = path.resolve(process.cwd(), dir);
+  let fullPath;
+  let tempDir = null;
   let errors = [];
   let warnings = [];
 
+  // Check if input is a GitHub URL
+  const githubMatch = dir.match(GITHUB_URL_PATTERN);
+
+  if (githubMatch) {
+    const [, owner, repo] = githubMatch;
+    const repoUrl = `https://github.com/${owner}/${repo}.git`;
+
+    console.log(pc.dim(`Cloning ${pc.cyan(`${owner}/${repo}`)} from GitHub...\n`));
+
+    try {
+      // Create temp directory
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "bl-theme-"));
+      fullPath = tempDir;
+
+      // Clone the repository (shallow clone for speed)
+      execSync(`git clone --depth 1 ${repoUrl} "${tempDir}"`, {
+        stdio: "pipe",
+      });
+
+      console.log(pc.green(`  Cloned successfully!\n`));
+    } catch (e) {
+      console.log(pc.red(`Error: Could not clone repository "${owner}/${repo}"`));
+      console.log(pc.dim(`  Make sure the repository exists and is publicly accessible.\n`));
+
+      if (e.message) {
+        console.log(pc.dim(`  ${e.message}`));
+      }
+
+      process.exit(1);
+    }
+  } else {
+    fullPath = path.resolve(process.cwd(), dir);
+  }
+
   console.log(pc.dim(`Validating theme at ${fullPath}...\n`));
 
   // Check directory exists
@@ -235,6 +335,10 @@ async function validate(dir) {
     process.exit(1);
   }
 
+  // Check for DESCRIPTION.md
+  const descriptionMdPath = path.join(fullPath, "DESCRIPTION.md");
+  const hasDescriptionMd = fs.existsSync(descriptionMdPath);
+
   // Check metadata.json
   const metadataPath = path.join(fullPath, "metadata.json");
   if (!fs.existsSync(metadataPath)) {
@@ -245,7 +349,6 @@ async function validate(dir) {
       const required = [
         "id",
         "title",
-        "description",
         "creators",
         "minVersion",
         "hasShaders",
@@ -259,6 +362,20 @@ async function validate(dir) {
         }
       }
 
+      // Check for description: either in metadata.json OR in DESCRIPTION.md
+      if (!metadata.description && !hasDescriptionMd) {
+        errors.push(
+          'Missing description: add "description" field in metadata.json or create DESCRIPTION.md'
+        );
+      }
+
+      if (hasDescriptionMd) {
+        const descContent = fs.readFileSync(descriptionMdPath, "utf-8").trim();
+        if (descContent.length === 0) {
+          errors.push("DESCRIPTION.md exists but is empty");
+        }
+      }
+
       if (metadata.id && !/^[a-z0-9-]+$/.test(metadata.id)) {
         errors.push(
           "metadata.json: id must be lowercase letters, numbers, and hyphens only"
@@ -273,6 +390,19 @@ async function validate(dir) {
         errors.push("metadata.json: images must be an array");
       }
 
+      // Check if images referenced in metadata.json exist in images/
+      if (metadata.images && Array.isArray(metadata.images)) {
+        const imagesDir = path.join(fullPath, "images");
+        for (const image of metadata.images) {
+          const imagePath = path.join(imagesDir, image);
+          if (!fs.existsSync(imagePath)) {
+            errors.push(
+              `metadata.json: image "${image}" not found in images/ directory`
+            );
+          }
+        }
+      }
+
       if (!metadata.tags) {
         warnings.push("metadata.json: consider adding tags for discoverability");
       }
@@ -302,6 +432,45 @@ async function validate(dir) {
       .filter((f) => /\.(png|jpg|jpeg|gif|webp)$/i.test(f));
     if (images.length === 0) {
       errors.push("images/ directory must contain at least one image");
+    } else {
+      // Validate each image
+      for (const image of images) {
+        const imagePath = path.join(imagesDir, image);
+
+        try {
+          const imageBuffer = fs.readFileSync(imagePath);
+          const dimensions = imageSize(imageBuffer);
+
+          if (!dimensions || !dimensions.width || !dimensions.height) {
+            errors.push(
+              `${pc.bold(image)}: Unable to read image dimensions - the file may be corrupted or in an unsupported format`
+            );
+            continue;
+          }
+
+          const { width, height } = dimensions;
+          const aspectRatio = (width / height).toFixed(2);
+          const recommendedAspectRatio = (RECOMMENDED_WIDTH / RECOMMENDED_HEIGHT).toFixed(2);
+
+          // Only warn if aspect ratio differs from recommended 16:9
+          if (aspectRatio !== recommendedAspectRatio) {
+            warnings.push(`${pc.bold(image)}: ${width}x${height} (aspect ratio ${aspectRatio})`);
+          }
+        } catch (e) {
+          // Handle corrupted or unreadable images
+          if (e.message.includes("unsupported") || e.message.includes("Invalid")) {
+            errors.push(
+              `${pc.bold(image)}: This image appears to be corrupted or in an unsupported format\n      ${pc.dim("Please ensure the file is a valid image (PNG, JPG, GIF, or WebP)")}`
+            );
+          } else if (e.code === "ENOENT") {
+            errors.push(`${pc.bold(image)}: File not found`);
+          } else {
+            errors.push(
+              `${pc.bold(image)}: Could not validate image - ${e.message}\n      ${pc.dim("The file may be corrupted or inaccessible")}`
+            );
+          }
+        }
+      }
     }
   }
 
@@ -330,12 +499,25 @@ async function validate(dir) {
     }
     if (warnings.length > 0) {
       console.log(pc.yellow(pc.bold("\n  Warnings:")));
+      console.log(pc.yellow("  Non-standard aspect ratios (recommended: 16:9)"));
       warnings.forEach((w) => console.log(pc.yellow(`    - ${w}`)));
+      console.log();
+      console.log(pc.dim(pc.yellow("  This is just a suggestion - your images will still work fine!")));
+      console.log(pc.dim(pc.yellow("  Different aspect ratios can be intentional for your theme's design.")));
     }
   }
 
   console.log();
 
+  // Cleanup temp directory if we cloned from GitHub
+  if (tempDir) {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch (e) {
+      // Ignore cleanup errors
+    }
+  }
+
   if (errors.length > 0) {
     process.exit(1);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bl-theme",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "CLI tool to scaffold Better Lyrics themes",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
   "author": "boidushya",
   "license": "MIT",
   "dependencies": {
-    "prompts": "^2.4.2",
-    "picocolors": "^1.1.1"
+    "image-size": "^2.0.2",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
   }
 }