create-bl-theme 1.0.4 → 1.0.6

package/PLAN.md

@@ -0,0 +1,399 @@
+# create-bl-theme - Implementation Plan
+
+This document outlines changes needed to support the new theme registry system.
+
+## Overview
+
+create-bl-theme is a CLI tool that:
+
+- Scaffolds new Better Lyrics themes
+- Validates theme structure and files
+- Provides RICS syntax validation
+
+This plan adds:
+
+- `publish` command to help creators set up auto-publishing
+- Updated validation for vendored structure
+- Semver validation improvements
+
+---
+
+## Current Structure
+
+```text
+create-bl-theme/
+├── bin/
+│   └── cli.js              # Main CLI implementation
+├── templates/
+│   ├── style.rics          # RICS template
+│   └── shader.json         # Shader template
+├── package.json
+└── README.md
+```
+
+### Current Commands
+
+| Command                    | Purpose                     |
+|----------------------------|-----------------------------|
+| `create-bl-theme [name]`   | Scaffold new theme          |
+| `create-bl-theme validate` | Validate theme structure    |
+
+---
+
+## New Command: `publish`
+
+Help creators set up auto-publishing via GitHub App.
+
+### Usage
+
+```bash
+# In theme repo directory
+create-bl-theme publish
+
+# Or specify path
+create-bl-theme publish ./my-theme
+```
+
+### What It Does
+
+1. **Check prerequisites**
+   - Validate theme structure first
+   - Check if repo is a git repository
+   - Check if repo has a remote
+
+2. **Guide through setup**
+   - Check if GitHub App is installed
+   - Provide installation link if not
+   - Verify theme is registered in better-lyrics/themes
+
+3. **Verify publishing works**
+   - Simulate what would happen on push
+   - Show current version and what would be published
+
+### Implementation
+
+```javascript
+// bin/cli.js (add to existing)
+
+async function publishCommand(args) {
+  const themePath = args[0] || '.';
+
+  console.log(chalk.blue('Checking theme for publishing...'));
+
+  // 1. Validate theme first
+  const validationResult = await validateTheme(themePath);
+  if (!validationResult.success) {
+    console.log(chalk.red('Theme validation failed. Fix errors before publishing.'));
+    process.exit(1);
+  }
+
+  // 2. Check git repo
+  const isGitRepo = await checkIsGitRepo(themePath);
+  if (!isGitRepo) {
+    console.log(chalk.red('Not a git repository. Initialize git first:'));
+    console.log(chalk.gray('  git init'));
+    console.log(chalk.gray('  git remote add origin https://github.com/username/theme-name.git'));
+    process.exit(1);
+  }
+
+  // 3. Get remote info
+  const remote = await getGitRemote(themePath);
+  if (!remote) {
+    console.log(chalk.red('No git remote found. Add a remote:'));
+    console.log(chalk.gray('  git remote add origin https://github.com/username/theme-name.git'));
+    process.exit(1);
+  }
+
+  // 4. Parse repo from remote
+  const repoMatch = remote.match(/github\.com[:/](.+?)(?:\.git)?$/);
+  if (!repoMatch) {
+    console.log(chalk.red('Could not parse GitHub repo from remote:', remote));
+    process.exit(1);
+  }
+  const repo = repoMatch[1];
+
+  // 5. Read metadata
+  const metadata = JSON.parse(fs.readFileSync(path.join(themePath, 'metadata.json'), 'utf8'));
+
+  console.log();
+  console.log(chalk.bold('Theme Info:'));
+  console.log(`  ID:      ${metadata.id}`);
+  console.log(`  Title:   ${metadata.title}`);
+  console.log(`  Version: ${metadata.version}`);
+  console.log(`  Repo:    ${repo}`);
+  console.log();
+
+  // 6. Check if registered
+  const isRegistered = await checkThemeRegistered(repo);
+
+  if (!isRegistered) {
+    console.log(chalk.yellow('Theme is not registered in the theme store.'));
+    console.log();
+    console.log(chalk.bold('To register your theme:'));
+    console.log('  1. Fork https://github.com/better-lyrics/themes');
+    console.log(`  2. Add { "repo": "${repo}" } to index.json`);
+    console.log('  3. Open a pull request');
+    console.log();
+    console.log('After your PR is merged, install the GitHub App for auto-updates:');
+    console.log(chalk.cyan('  https://github.com/apps/better-lyrics-themes'));
+    process.exit(0);
+  }
+
+  // 7. Check if GitHub App is installed
+  console.log(chalk.green('Theme is registered in the theme store.'));
+  console.log();
+  console.log(chalk.bold('Auto-publishing Setup:'));
+  console.log();
+  console.log('To enable automatic updates when you push:');
+  console.log('  1. Install the GitHub App on your repo:');
+  console.log(chalk.cyan('     https://github.com/apps/better-lyrics-themes'));
+  console.log();
+  console.log('  2. Push changes to your repo:');
+  console.log(chalk.gray('     git add .'));
+  console.log(chalk.gray('     git commit -m "feat: update theme"'));
+  console.log(chalk.gray('     git push'));
+  console.log();
+  console.log('The registry will automatically:');
+  console.log('  - Validate your theme');
+  console.log('  - Update the lockfile');
+  console.log('  - Vendor your theme files');
+  console.log('  - Show a commit status on your push');
+  console.log();
+
+  // 8. Check current lockfile status
+  const lockStatus = await checkLockStatus(repo);
+  if (lockStatus) {
+    console.log(chalk.bold('Current Registry Status:'));
+    console.log(`  Locked Version: ${lockStatus.version}`);
+    console.log(`  Locked At:      ${lockStatus.locked}`);
+    console.log(`  Commit:         ${lockStatus.commit.slice(0, 7)}`);
+
+    if (metadata.version === lockStatus.version) {
+      console.log();
+      console.log(chalk.yellow('Your local version matches the registry.'));
+      console.log('Bump the version in metadata.json to publish an update.');
+    } else {
+      const semver = require('semver');
+      if (semver.gt(metadata.version, lockStatus.version)) {
+        console.log();
+        console.log(chalk.green(`Ready to publish: ${lockStatus.version} -> ${metadata.version}`));
+        console.log('Push to your repo to trigger an update.');
+      } else {
+        console.log();
+        console.log(chalk.red(`Version ${metadata.version} is not greater than ${lockStatus.version}`));
+        console.log('Versions must increase. Update metadata.json with a higher version.');
+      }
+    }
+  }
+}
+
+async function checkThemeRegistered(repo) {
+  try {
+    const response = await fetch(
+      'https://raw.githubusercontent.com/better-lyrics/themes/main/index.json'
+    );
+    const index = await response.json();
+    return index.themes?.some(t => t.repo === repo) ?? false;
+  } catch {
+    return false;
+  }
+}
+
+async function checkLockStatus(repo) {
+  try {
+    const response = await fetch(
+      'https://raw.githubusercontent.com/better-lyrics/themes/main/index.lock.json'
+    );
+    const lock = await response.json();
+    return lock.themes?.find(t => t.repo === repo) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function checkIsGitRepo(themePath) {
+  try {
+    execSync('git rev-parse --git-dir', { cwd: themePath, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function getGitRemote(themePath) {
+  try {
+    return execSync('git remote get-url origin', { cwd: themePath, encoding: 'utf8' }).trim();
+  } catch {
+    return null;
+  }
+}
+```
+
+---
+
+## Updated Validation
+
+### Add Semver Validation
+
+```javascript
+// In validateTheme function
+
+// Validate version format
+const version = metadata.version;
+const semverRegex = /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/;
+
+if (!semverRegex.test(version)) {
+  errors.push({
+    type: 'error',
+    message: `Invalid version format: "${version}". Must be semver (e.g., 1.0.0, 1.0.0-beta.1)`,
+  });
+}
+```
+
+### Validate Required Files for Registry
+
+```javascript
+// Ensure files needed for vendoring exist
+
+const requiredFiles = ['metadata.json'];
+const styleFiles = ['style.rics', 'style.css'];
+
+// Check style file exists
+const hasStyleFile = styleFiles.some(f => fs.existsSync(path.join(themePath, f)));
+if (!hasStyleFile) {
+  errors.push({
+    type: 'error',
+    message: 'Missing style file. Create style.rics or style.css',
+  });
+}
+
+// Check images directory
+const imagesDir = path.join(themePath, 'images');
+if (!fs.existsSync(imagesDir)) {
+  errors.push({
+    type: 'error',
+    message: 'Missing images/ directory. Add at least one screenshot.',
+  });
+} else {
+  const images = fs.readdirSync(imagesDir).filter(f =>
+    /\.(png|jpg|jpeg|gif|webp)$/i.test(f)
+  );
+  if (images.length === 0) {
+    errors.push({
+      type: 'error',
+      message: 'No images found in images/ directory. Add at least one screenshot.',
+    });
+  }
+}
+
+// Validate images array matches actual files
+const declaredImages = metadata.images || [];
+for (const img of declaredImages) {
+  if (!fs.existsSync(path.join(imagesDir, img))) {
+    errors.push({
+      type: 'error',
+      message: `Image "${img}" declared in metadata.json but not found in images/`,
+    });
+  }
+}
+
+// Check shader.json if hasShaders is true
+if (metadata.hasShaders && !fs.existsSync(path.join(themePath, 'shader.json'))) {
+  errors.push({
+    type: 'error',
+    message: 'hasShaders is true but shader.json not found',
+  });
+}
+
+// Check description exists (metadata or DESCRIPTION.md)
+const hasDescription = metadata.description || fs.existsSync(path.join(themePath, 'DESCRIPTION.md'));
+if (!hasDescription) {
+  errors.push({
+    type: 'error',
+    message: 'Missing description. Add "description" to metadata.json or create DESCRIPTION.md',
+  });
+}
+```
+
+### Validate Cover Image
+
+```javascript
+// Check cover.png or first image in images array
+const hasCoverPng = fs.existsSync(path.join(themePath, 'cover.png'));
+const hasImagesArray = metadata.images && metadata.images.length > 0;
+
+if (!hasCoverPng && !hasImagesArray) {
+  warnings.push({
+    type: 'warning',
+    message: 'No cover image. Add cover.png or images to the images/ folder.',
+  });
+}
+```
+
+---
+
+## Updated CLI Help
+
+```javascript
+function showHelp() {
+  console.log(`
+${chalk.bold('create-bl-theme')} - CLI for Better Lyrics themes
+
+${chalk.bold('Usage:')}
+  create-bl-theme [theme-name]     Create a new theme
+  create-bl-theme validate [path]  Validate a theme
+  create-bl-theme publish [path]   Check publishing status
+
+${chalk.bold('Examples:')}
+  create-bl-theme my-theme
+  create-bl-theme validate ./my-theme
+  create-bl-theme publish
+
+${chalk.bold('Theme Structure:')}
+  my-theme/
+  ├── metadata.json        # Required - Theme metadata
+  ├── style.rics           # Required - Styles (or style.css)
+  ├── shader.json          # Optional - If hasShaders: true
+  ├── DESCRIPTION.md       # Optional - Rich description
+  ├── cover.png            # Optional - Cover image
+  └── images/              # Required - Screenshots
+      └── preview.png
+
+${chalk.bold('Documentation:')}
+  https://github.com/better-lyrics/themes
+  `);
+}
+```
+
+---
+
+## Package.json Updates
+
+```json
+{
+  "dependencies": {
+    "semver": "^7.5.0"
+  }
+}
+```
+
+---
+
+## Action Items
+
+- [ ] Add `publish` command
+- [ ] Add semver validation to validate command
+- [ ] Validate all required files for vendoring
+- [ ] Add cover.png validation
+- [ ] Update help text
+- [ ] Add semver dependency
+- [ ] Update README with publish command docs
+- [ ] Test with existing themes
+
+---
+
+## Related Documents
+
+- [better-lyrics-themes PLAN.md](../better-lyrics-themes/PLAN.md)
+- [store-api PLAN.md](../store-api/PLAN.md)
+- [better-lyrics PLAN.md](../better-lyrics/PLAN.md)

package/README.md

@@ -42,7 +42,8 @@ create-bl-theme validate https://github.com/username/theme-repo
 ```
 
 The validator checks:
-- Required files (metadata.json, style.css, images/)
+- 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)
@@ -52,7 +53,7 @@ The validator checks:
 ```
 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
@@ -60,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:
@@ -77,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).
 
@@ -85,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

@@ -8,6 +8,7 @@ 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);
@@ -35,6 +36,11 @@ async function main() {
     return;
   }
 
+  if (command === "publish") {
+    await publish(args[1] || ".");
+    return;
+  }
+
   if (command === "help" || command === "--help" || command === "-h") {
     showHelp();
     return;
@@ -47,11 +53,26 @@ function showHelp() {
   console.log(`${pc.bold("Usage:")}
   ${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.cyan("create-bl-theme")} publish [dir]       Check publishing status
 
 ${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
+  ${pc.dim("$")} create-bl-theme publish
+
+${pc.bold("Theme Structure:")}
+  my-theme/
+  ├── metadata.json        ${pc.dim("# Required - Theme metadata")}
+  ├── style.rics           ${pc.dim("# Required - Styles (or style.css)")}
+  ├── shader.json          ${pc.dim("# Optional - If hasShaders: true")}
+  ├── DESCRIPTION.md       ${pc.dim("# Optional - Rich description")}
+  ├── cover.png            ${pc.dim("# Optional - Cover image")}
+  └── images/              ${pc.dim("# Required - Screenshots")}
+      └── preview.png
+
+${pc.bold("Documentation:")}
+  ${pc.cyan("https://github.com/better-lyrics/themes")}
 `);
 }
 
@@ -212,12 +233,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) {
@@ -261,7 +282,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")}`
   );
@@ -277,9 +298,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}`)
@@ -362,6 +389,16 @@ async function validate(dir) {
         }
       }
 
+      // Validate version format (semver)
+      if (metadata.version) {
+        const semverRegex = /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/;
+        if (!semverRegex.test(metadata.version)) {
+          errors.push(
+            `metadata.json: invalid version format "${metadata.version}". Must be semver (e.g., 1.0.0, 1.0.0-beta.1)`
+          );
+        }
+      }
+
       // Check for description: either in metadata.json OR in DESCRIPTION.md
       if (!metadata.description && !hasDescriptionMd) {
         errors.push(
@@ -411,12 +448,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");
     }
@@ -489,6 +555,21 @@ async function validate(dir) {
     }
   }
 
+  // Check for cover image (cover.png or first image in images array)
+  if (fs.existsSync(metadataPath)) {
+    try {
+      const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+      const hasCoverPng = fs.existsSync(path.join(fullPath, "cover.png"));
+      const hasImagesArray = metadata.images && metadata.images.length > 0;
+
+      if (!hasCoverPng && !hasImagesArray) {
+        warnings.push("No cover image found. Add cover.png or images to the images/ folder.");
+      }
+    } catch (e) {
+      // Already reported JSON error above
+    }
+  }
+
   // Print results
   if (errors.length === 0 && warnings.length === 0) {
     console.log(pc.green("  All checks passed!"));
@@ -523,6 +604,185 @@ async function validate(dir) {
   }
 }
 
+async function publish(dir) {
+  const fullPath = path.resolve(process.cwd(), dir);
+
+  console.log(pc.dim(`Checking theme for publishing...\n`));
+
+  // Check directory exists
+  if (!fs.existsSync(fullPath)) {
+    console.log(pc.red(`Error: Directory "${dir}" does not exist.`));
+    process.exit(1);
+  }
+
+  // 1. Validate theme first (simple check, not full validation)
+  const metadataPath = path.join(fullPath, "metadata.json");
+  if (!fs.existsSync(metadataPath)) {
+    console.log(pc.red("Error: metadata.json not found."));
+    console.log(pc.dim("Run validation first: create-bl-theme validate"));
+    process.exit(1);
+  }
+
+  let metadata;
+  try {
+    metadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+  } catch (e) {
+    console.log(pc.red(`Error: Invalid metadata.json - ${e.message}`));
+    process.exit(1);
+  }
+
+  // 2. Check git repo
+  if (!checkIsGitRepo(fullPath)) {
+    console.log(pc.red("Not a git repository. Initialize git first:"));
+    console.log(pc.dim("  git init"));
+    console.log(pc.dim("  git remote add origin https://github.com/username/theme-name.git"));
+    process.exit(1);
+  }
+
+  // 3. Get remote info
+  const remote = getGitRemote(fullPath);
+  if (!remote) {
+    console.log(pc.red("No git remote found. Add a remote:"));
+    console.log(pc.dim("  git remote add origin https://github.com/username/theme-name.git"));
+    process.exit(1);
+  }
+
+  // 4. Parse repo from remote
+  const repoMatch = remote.match(/github\.com[:/](.+?)(?:\.git)?$/);
+  if (!repoMatch) {
+    console.log(pc.red("Could not parse GitHub repo from remote:"), remote);
+    process.exit(1);
+  }
+  const repo = repoMatch[1].replace(/\.git$/, "");
+
+  // 5. Display theme info
+  console.log(pc.bold("Theme Info:"));
+  console.log(`  ID:      ${metadata.id}`);
+  console.log(`  Title:   ${metadata.title}`);
+  console.log(`  Version: ${metadata.version}`);
+  console.log(`  Repo:    ${repo}`);
+  console.log();
+
+  // 6. Check if registered
+  const isRegistered = await checkThemeRegistered(repo);
+
+  if (!isRegistered) {
+    console.log(pc.yellow("Theme is not registered in the theme store."));
+    console.log();
+    console.log(pc.bold("To register your theme:"));
+    console.log("  1. Fork https://github.com/better-lyrics/themes");
+    console.log(`  2. Add { "repo": "${repo}" } to index.json`);
+    console.log("  3. Open a pull request");
+    console.log();
+    console.log("After your PR is merged, install the GitHub App for auto-updates:");
+    console.log(pc.cyan("  https://github.com/marketplace/better-lyrics-themes"));
+    process.exit(0);
+  }
+
+  // 7. Theme is registered
+  console.log(pc.green("Theme is registered in the theme store."));
+  console.log();
+  console.log(pc.bold("Auto-publishing Setup:"));
+  console.log();
+  console.log("To enable automatic updates when you push:");
+  console.log("  1. Install the GitHub App on your repo:");
+  console.log(pc.cyan("     https://github.com/marketplace/better-lyrics-themes"));
+  console.log();
+  console.log("  2. Push changes to your repo:");
+  console.log(pc.dim("     git add ."));
+  console.log(pc.dim('     git commit -m "feat: update theme"'));
+  console.log(pc.dim("     git push"));
+  console.log();
+  console.log("The registry will automatically:");
+  console.log("  - Validate your theme");
+  console.log("  - Update the lockfile");
+  console.log("  - Vendor your theme files");
+  console.log("  - Show a commit status on your push");
+  console.log();
+
+  // 8. Check current lockfile status
+  const lockStatus = await checkLockStatus(repo);
+  if (lockStatus) {
+    console.log(pc.bold("Current Registry Status:"));
+    console.log(`  Locked Version: ${lockStatus.version}`);
+    console.log(`  Locked At:      ${lockStatus.locked}`);
+    console.log(`  Commit:         ${lockStatus.commit.slice(0, 7)}`);
+
+    if (metadata.version === lockStatus.version) {
+      console.log();
+      console.log(pc.yellow("Your local version matches the registry."));
+      console.log("Bump the version in metadata.json to publish an update.");
+    } else {
+      // Compare versions
+      const localParts = metadata.version.split(".").map(Number);
+      const remoteParts = lockStatus.version.split(".").map(Number);
+      let isGreater = false;
+
+      for (let i = 0; i < 3; i++) {
+        if (localParts[i] > remoteParts[i]) {
+          isGreater = true;
+          break;
+        } else if (localParts[i] < remoteParts[i]) {
+          break;
+        }
+      }
+
+      if (isGreater) {
+        console.log();
+        console.log(pc.green(`Ready to publish: ${lockStatus.version} -> ${metadata.version}`));
+        console.log("Push to your repo to trigger an update.");
+      } else {
+        console.log();
+        console.log(pc.red(`Version ${metadata.version} is not greater than ${lockStatus.version}`));
+        console.log("Versions must increase. Update metadata.json with a higher version.");
+      }
+    }
+  }
+
+  console.log();
+}
+
+function checkIsGitRepo(themePath) {
+  try {
+    execSync("git rev-parse --git-dir", { cwd: themePath, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getGitRemote(themePath) {
+  try {
+    return execSync("git remote get-url origin", { cwd: themePath, encoding: "utf8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
+async function checkThemeRegistered(repo) {
+  try {
+    const response = await fetch(
+      "https://raw.githubusercontent.com/better-lyrics/themes/main/index.json"
+    );
+    const index = await response.json();
+    return index.themes?.some((t) => t.repo === repo) ?? false;
+  } catch {
+    return false;
+  }
+}
+
+async function checkLockStatus(repo) {
+  try {
+    const response = await fetch(
+      "https://raw.githubusercontent.com/better-lyrics/themes/main/index.lock.json"
+    );
+    const lock = await response.json();
+    return lock.themes?.find((t) => t.repo === repo) ?? null;
+  } catch {
+    return null;
+  }
+}
+
 main().catch((err) => {
   console.error(pc.red(err.message));
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bl-theme",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "CLI tool to scaffold Better Lyrics themes",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
   "dependencies": {
     "image-size": "^2.0.2",
     "picocolors": "^1.1.1",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "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
- */