create-bl-theme 1.0.3 → 1.0.5

package/README.md

@@ -34,17 +34,26 @@ 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.rics or style.css, images/)
+- RICS syntax validation (for .rics files)
+- 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)
+├── style.rics       # Your styles in RICS format (required)
 ├── DESCRIPTION.md   # Rich description (optional, takes precedence)
 ├── shader.json      # Shader config (if enabled)
 ├── README.md        # Theme documentation
@@ -52,6 +61,33 @@ my-theme/
     └── preview.png
 ```
 
+## RICS
+
+Themes use [RICS](https://github.com/better-lyrics/rics) - a lightweight CSS preprocessor with full CSS parity. RICS adds variables, nesting, and mixins while staying close to standard CSS.
+
+**Any valid CSS is also valid RICS**, so you can write plain CSS if you prefer.
+
+```scss
+$accent: #ff6b6b;
+
+.lyrics-container {
+  background: rgba(0, 0, 0, 0.8);
+
+  .lyrics-line {
+    color: $accent;
+
+    &.active {
+      font-weight: bold;
+    }
+  }
+}
+```
+
+- **Playground:** https://rics.boidu.dev
+- **RICS Docs:** https://github.com/better-lyrics/rics
+
+> **Note:** Both `.rics` and `.css` files are supported. The validator prefers `.rics` if both exist.
+
 ### Theme Description Options
 
 You can provide your theme description in two ways:
@@ -69,7 +105,7 @@ Better Lyrics supports **GitHub Flavored Markdown (GFM)** in DESCRIPTION.md, so
 
 ## Theme Development
 
-1. **Edit `style.css`** - Add your custom styles. Use browser DevTools to inspect Better Lyrics elements and find the right selectors.
+1. **Edit `style.rics`** - Add your custom styles using RICS or plain CSS. Use browser DevTools to inspect Better Lyrics elements and find the right selectors.
 
 2. **Add screenshots** - Place at least one preview image in `images/`. Recommended size: 1280x720 (16:9 aspect ratio).
 
@@ -77,10 +113,13 @@ Better Lyrics supports **GitHub Flavored Markdown (GFM)** in DESCRIPTION.md, so
 
 4. **Test locally** - Install your theme via "Install from URL" in Better Lyrics using your local path or GitHub repo URL.
 
+**Resources:**
+- [Styling Guide](https://github.com/better-lyrics/better-lyrics/blob/master/STYLING.md) - Available selectors and styling reference
+
 ## Submitting to Theme Store
 
 1. Push your theme to a GitHub repository
-2. Fork [better-lyrics-themes](https://github.com/better-lyrics/better-lyrics-themes)
+2. Fork [themes](https://github.com/better-lyrics/themes)
 3. Add your theme to `index.json`:
    ```json
    {

package/bin/cli.js

@@ -4,13 +4,24 @@ 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";
+import { compileWithDetails } from "rics";
 
 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 +46,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
 `);
 }
 
@@ -201,12 +213,12 @@ Any special instructions for using this theme.
     fs.writeFileSync(path.join(fullPath, "DESCRIPTION.md"), descriptionMd);
   }
 
-  // Create style.css from template
-  const cssTemplate = fs.readFileSync(
-    path.join(TEMPLATES_DIR, "style.css"),
+  // Create style.rics from template
+  const ricsTemplate = fs.readFileSync(
+    path.join(TEMPLATES_DIR, "style.rics"),
     "utf-8"
   );
-  fs.writeFileSync(path.join(fullPath, "style.css"), cssTemplate);
+  fs.writeFileSync(path.join(fullPath, "style.rics"), ricsTemplate);
 
   // Create shader.json if needed
   if (response.hasShaders) {
@@ -250,7 +262,7 @@ MIT
   console.log();
   console.log(pc.bold("  Next steps:"));
   console.log(`  ${pc.dim("1.")} cd ${dir}`);
-  console.log(`  ${pc.dim("2.")} Edit ${pc.cyan("style.css")} with your theme styles`);
+  console.log(`  ${pc.dim("2.")} Edit ${pc.cyan("style.rics")} with your theme styles`);
   console.log(
     `  ${pc.dim("3.")} Add a preview screenshot to ${pc.cyan("images/preview.png")}`
   );
@@ -266,9 +278,15 @@ MIT
   console.log(
     `  ${pc.dim(`${stepNum}.`)} Push to GitHub and submit to the theme store`
   );
-  console.log(
-    `      ${pc.dim("https://github.com/boidushya/better-lyrics-themes")}`
-  );
+  console.log();
+  console.log(pc.bold("  Resources:"));
+  console.log(`  ${pc.cyan("RICS")} is a lightweight CSS preprocessor with full CSS parity.`);
+  console.log(`  It adds variables, nesting, and mixins - but plain CSS works too!`);
+  console.log();
+  console.log(`  ${pc.dim("Playground:")}     https://rics.boidu.dev`);
+  console.log(`  ${pc.dim("RICS Docs:")}      https://github.com/better-lyrics/rics`);
+  console.log(`  ${pc.dim("Styling Guide:")}  https://github.com/better-lyrics/better-lyrics/blob/master/STYLING.md`);
+  console.log(`  ${pc.dim("Submit Theme:")}   https://github.com/better-lyrics/themes`);
   console.log();
   console.log(
     pc.dim("  Validate your theme with: ") + pc.cyan(`npx create-bl-theme@latest validate ${dir}`)
@@ -277,10 +295,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
@@ -344,6 +397,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");
       }
@@ -352,12 +418,41 @@ async function validate(dir) {
     }
   }
 
-  // Check style.css
-  const stylePath = path.join(fullPath, "style.css");
-  if (!fs.existsSync(stylePath)) {
-    errors.push("style.css is missing");
-  } else {
-    const css = fs.readFileSync(stylePath, "utf-8");
+  // Check for style.rics or style.css (prefer .rics)
+  const ricsPath = path.join(fullPath, "style.rics");
+  const cssPath = path.join(fullPath, "style.css");
+  const hasRics = fs.existsSync(ricsPath);
+  const hasCss = fs.existsSync(cssPath);
+
+  if (!hasRics && !hasCss) {
+    errors.push("Missing required file: style.rics or style.css");
+  } else if (hasRics) {
+    const ricsSource = fs.readFileSync(ricsPath, "utf-8");
+    if (ricsSource.trim().length === 0) {
+      warnings.push("style.rics is empty");
+    } else {
+      // Validate RICS syntax
+      try {
+        const result = compileWithDetails(ricsSource);
+        if (result.errors && result.errors.length > 0) {
+          for (const err of result.errors) {
+            const location = err.start
+              ? ` (line ${err.start.line}, column ${err.start.column})`
+              : "";
+            errors.push(`style.rics: ${err.message}${location}`);
+          }
+        }
+        if (result.warnings && result.warnings.length > 0) {
+          for (const warn of result.warnings) {
+            warnings.push(`style.rics: ${warn.message || warn}`);
+          }
+        }
+      } catch (e) {
+        errors.push(`style.rics: Failed to compile - ${e.message}`);
+      }
+    }
+  } else if (hasCss) {
+    const css = fs.readFileSync(cssPath, "utf-8");
     if (css.trim().length === 0) {
       warnings.push("style.css is empty");
     }
@@ -373,6 +468,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")}`
+            );
+          }
+        }
+      }
     }
   }
 
@@ -401,12 +535,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.3",
+  "version": "1.0.5",
   "description": "CLI tool to scaffold Better Lyrics themes",
   "type": "module",
   "bin": {
@@ -18,7 +18,9 @@
   "author": "boidushya",
   "license": "MIT",
   "dependencies": {
+    "image-size": "^2.0.2",
+    "picocolors": "^1.1.1",
     "prompts": "^2.4.2",
-    "picocolors": "^1.1.1"
+    "rics": "^0.3.7"
   }
 }

package/templates/style.rics

@@ -0,0 +1,11 @@
+/*
+ * Better Lyrics Theme
+ *
+ * This file uses RICS - a lightweight CSS preprocessor with full CSS parity.
+ * RICS adds variables, nesting, and mixins while staying close to standard CSS.
+ * Any valid CSS is also valid RICS, so you can write plain CSS if you prefer.
+ *
+ * RICS Playground: https://rics.boidu.dev
+ * RICS Docs:       https://github.com/better-lyrics/rics
+ * Styling Guide:   https://github.com/better-lyrics/better-lyrics/blob/master/STYLING.md
+ */

package/templates/style.css

@@ -1,6 +0,0 @@
-/*
- * Better Lyrics Theme
- *
- * For available selectors and styling guide, see:
- * https://github.com/better-lyrics/better-lyrics/blob/master/STYLING.md
- */