create-bl-theme 1.0.7 → 1.0.9

package/.claude/settings.local.json

@@ -1,7 +1,10 @@
 {
   "permissions": {
     "allow": [
-      "Bash(cat:*)"
+      "Bash(cat:*)",
+      "Bash(node /Users/boidu/Developer/create-bl-theme/bin/cli.js bump:*)",
+      "Bash(npm:*)",
+      "Bash(node /Users/boidu/Developer/create-bl-theme/bin/cli.js:*)"
     ],
     "deny": [],
     "ask": []

package/CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**create-bl-theme** is a CLI tool for scaffolding and managing themes for the Better Lyrics browser extension. It provides commands to create new themes, validate their structure, manage versioning, and handle publishing to a theme registry.
+
+## Commands
+
+```bash
+# Run the CLI locally during development
+node bin/cli.js [command]
+
+# Create a new theme (interactive prompts)
+node bin/cli.js [theme-name]
+
+# Validate a theme (supports local paths or GitHub URLs)
+node bin/cli.js validate [dir|url]
+
+# Check publishing status against the theme registry
+node bin/cli.js publish [dir]
+
+# Bump version (patch/minor/major)
+node bin/cli.js bump [patch|minor|major] [dir]
+
+# Show version/help
+node bin/cli.js --version
+node bin/cli.js --help
+```
+
+## Architecture
+
+The entire CLI is implemented in a single file: `bin/cli.js` (ES6 module).
+
+**Main routing pattern:**
+- `main()` parses `process.argv` and routes to command handlers
+- Commands: `create()`, `validate()`, `publish()`, `bump()`
+
+**Key external dependencies:**
+- `rics` - RICS CSS preprocessor for syntax validation via `compileWithDetails()`
+- `prompts` - Interactive CLI prompts
+- `image-size` - Image dimension validation
+- `picocolors` - Terminal colors
+
+**External API calls:**
+- Theme registry: `https://raw.githubusercontent.com/better-lyrics/themes/master/index.json`
+- Lock file: `https://raw.githubusercontent.com/better-lyrics/themes/master/index.lock.json`
+
+## Theme Structure Generated
+
+```
+theme-name/
+├── metadata.json      # Required: id, title, creators, minVersion, hasShaders, version, images
+├── style.rics         # Required: styles using RICS preprocessor (plain CSS is valid)
+├── images/            # Required: at least one screenshot
+├── DESCRIPTION.md     # Optional: rich markdown description
+├── shader.json        # Required if hasShaders: true
+└── README.md
+```
+
+## Validation Rules
+
+- `metadata.json` requires fields: id, title, creators, minVersion, hasShaders, version, images
+- Version must be strict semver (e.g., `1.0.0`)
+- Image IDs: lowercase letters, numbers, hyphens only
+- Images: PNG, JPG, GIF, WebP; warns if not 16:9 aspect ratio
+- RICS syntax validated with detailed error reporting
+- Shader.json required when `hasShaders: true`
+
+## RICS Notes
+
+RICS is a lightweight CSS preprocessor with full CSS parity. Plain CSS is valid RICS. Supports variables, nesting, mixins. Documentation: https://github.com/better-lyrics/rics

package/README.md

@@ -45,9 +45,41 @@ 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
+- Semver version format
 - Image integrity (detects corrupted files)
 - Image dimensions (recommends 1280x720, but other sizes work fine)
 
+### Bump version
+
+```bash
+# Bump patch version (1.0.0 → 1.0.1)
+create-bl-theme bump patch
+
+# Bump minor version (1.0.0 → 1.1.0)
+create-bl-theme bump minor
+
+# Bump major version (1.0.0 → 2.0.0)
+create-bl-theme bump major
+
+# Bump in a specific directory
+create-bl-theme bump patch ./my-theme
+```
+
+### Check publishing status
+
+```bash
+# Check if theme is registered and ready to publish
+create-bl-theme publish
+
+# Check a specific directory
+create-bl-theme publish ./my-theme
+```
+
+The publish command:
+- Checks if your theme is registered in the theme store
+- Shows your current version vs. the registry version
+- Provides setup instructions for auto-publishing
+
 ## Generated Structure
 
 ```
@@ -130,6 +162,16 @@ Better Lyrics supports **GitHub Flavored Markdown (GFM)** in DESCRIPTION.md, so
    ```
 4. Open a pull request
 
+### Auto-Publishing
+
+After your theme is registered, install the [Better Lyrics Themes](https://github.com/marketplace/better-lyrics-themes) GitHub App on your repo. This enables automatic updates:
+
+1. Bump your version: `create-bl-theme bump patch`
+2. Commit and push
+3. The registry automatically validates and publishes your update
+
+Use `create-bl-theme publish` to check your publishing status.
+
 ## License
 
 MIT

package/bin/cli.js

@@ -7,7 +7,7 @@ import path from "path";
 import os from "os";
 import { fileURLToPath } from "url";
 import { imageSize } from "image-size";
-import { execSync } from "child_process";
+import { execSync, spawn } from "child_process";
 import { compileWithDetails } from "rics";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -22,12 +22,95 @@ const RECOMMENDED_HEIGHT = 720;
 // GitHub URL patterns
 const GITHUB_URL_PATTERN = /^(?:https?:\/\/)?(?:www\.)?github\.com\/([^\/]+)\/([^\/]+)(?:\/)?(?:\.git)?$/;
 
+// GitHub App URL for auto-updates
+const GITHUB_APP_URL = "https://github.com/apps/better-lyrics-harmonizer/installations/new";
+
+// Load package.json for version
+const pkg = JSON.parse(
+  fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf-8")
+);
+
+// Cross-platform browser opener
+function openBrowser(url) {
+  const platform = process.platform;
+  let command;
+  let args;
+
+  if (platform === "darwin") {
+    command = "open";
+    args = [url];
+  } else if (platform === "win32") {
+    command = "cmd";
+    args = ["/c", "start", "", url];
+  } else {
+    command = "xdg-open";
+    args = [url];
+  }
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: "ignore",
+    });
+
+    child.on("error", (err) => {
+      reject(err);
+    });
+
+    child.unref();
+    resolve();
+  });
+}
+
+// Prompt to install GitHub App for auto-updates
+async function promptGitHubAppInstall() {
+  console.log();
+  console.log(pc.bold("GitHub App Installation"));
+  console.log();
+  console.log("Install Better Lyrics Harmonizer for automatic theme publishing.");
+  console.log(pc.dim("This is a one-time setup. After installing, push changes with a bumped"));
+  console.log(pc.dim("version and they'll auto-publish to the theme store (with commit status)."));
+  console.log();
+
+  const response = await prompts({
+    type: "confirm",
+    name: "openBrowser",
+    message: "Open browser to install Better Lyrics Harmonizer?",
+    initial: true,
+  });
+
+  if (response.openBrowser) {
+    try {
+      await openBrowser(GITHUB_APP_URL);
+      console.log(pc.green("  Browser opened!"));
+    } catch (err) {
+      console.log(pc.yellow("  Could not open browser automatically."));
+    }
+  }
+
+  console.log();
+  console.log(pc.dim("  Install URL:"));
+  console.log(pc.cyan(`  ${GITHUB_APP_URL}`));
+  console.log();
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
 
+  // Handle flags first (no banner)
+  if (command === "--version" || command === "-v" || command === "version") {
+    console.log(pkg.version);
+    return;
+  }
+
+  if (command === "--help" || command === "-h" || command === "help") {
+    showHelp();
+    return;
+  }
+
   console.log();
-  console.log(pc.bold(pc.cyan("  Better Lyrics Theme Creator")));
+  console.log(pc.bold(pc.cyan("  Better Lyrics Theme Creator")) + pc.dim(` v${pkg.version}`));
   console.log(pc.dim("  Create themes for Better Lyrics extension"));
   console.log();
 
@@ -41,8 +124,8 @@ async function main() {
     return;
   }
 
-  if (command === "help" || command === "--help" || command === "-h") {
-    showHelp();
+  if (command === "bump") {
+    await bump(args[1], args[2]);
     return;
   }
 
@@ -50,16 +133,27 @@ async function main() {
 }
 
 function showHelp() {
-  console.log(`${pc.bold("Usage:")}
+  console.log(`
+${pc.bold(pc.cyan("create-bl-theme"))} ${pc.dim(`v${pkg.version}`)}
+CLI for Better Lyrics themes
+
+${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.cyan("create-bl-theme")} bump [type] [dir]   Bump version (patch, minor, major)
+
+${pc.bold("Options:")}
+  ${pc.cyan("-v, --version")}  Show version number
+  ${pc.cyan("-h, --help")}     Show this help message
 
 ${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.dim("$")} create-bl-theme bump patch
+  ${pc.dim("$")} create-bl-theme bump minor ./my-theme
 
 ${pc.bold("Theme Structure:")}
   my-theme/
@@ -590,6 +684,11 @@ async function validate(dir) {
 
   console.log();
 
+  // Prompt to install GitHub App if validation passed
+  if (errors.length === 0) {
+    await promptGitHubAppInstall();
+  }
+
   // Cleanup temp directory if we cloned from GitHub
   if (tempDir) {
     try {
@@ -674,30 +773,23 @@ async function publish(dir) {
     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"));
+    console.log(pc.dim("After your PR is merged, install the GitHub App for auto-updates:"));
+    await promptGitHubAppInstall();
     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(pc.bold("To publish updates:"));
+  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
@@ -739,7 +831,8 @@ async function publish(dir) {
     }
   }
 
-  console.log();
+  // Prompt to install GitHub App for auto-updates
+  await promptGitHubAppInstall();
 }
 
 function checkIsGitRepo(themePath) {
@@ -788,6 +881,90 @@ async function checkLockStatus(repo) {
   }
 }
 
+async function bump(typeOrDir, dirArg) {
+  // Handle flexible argument order: bump [type] [dir] or bump [dir]
+  let type = "patch";
+  let dir = ".";
+
+  const validTypes = ["patch", "minor", "major"];
+
+  if (typeOrDir) {
+    if (validTypes.includes(typeOrDir)) {
+      type = typeOrDir;
+      dir = dirArg || ".";
+    } else {
+      // Assume it's a directory
+      dir = typeOrDir;
+    }
+  }
+
+  const fullPath = path.resolve(process.cwd(), dir);
+  const metadataPath = path.join(fullPath, "metadata.json");
+
+  // Check metadata.json exists
+  if (!fs.existsSync(metadataPath)) {
+    console.log(pc.red("Error: metadata.json not found."));
+    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);
+  }
+
+  const currentVersion = metadata.version;
+  if (!currentVersion) {
+    console.log(pc.red("Error: No version field in metadata.json"));
+    process.exit(1);
+  }
+
+  // Parse current version
+  const match = currentVersion.match(/^(\d+)\.(\d+)\.(\d+)(.*)$/);
+  if (!match) {
+    console.log(pc.red(`Error: Invalid version format "${currentVersion}"`));
+    process.exit(1);
+  }
+
+  let [, major, minor, patch, prerelease] = match;
+  major = parseInt(major, 10);
+  minor = parseInt(minor, 10);
+  patch = parseInt(patch, 10);
+
+  // Bump version
+  switch (type) {
+    case "major":
+      major++;
+      minor = 0;
+      patch = 0;
+      prerelease = "";
+      break;
+    case "minor":
+      minor++;
+      patch = 0;
+      prerelease = "";
+      break;
+    case "patch":
+    default:
+      patch++;
+      prerelease = "";
+      break;
+  }
+
+  const newVersion = `${major}.${minor}.${patch}`;
+  metadata.version = newVersion;
+
+  // Write back
+  fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + "\n");
+
+  console.log(pc.green(`  ${currentVersion} → ${newVersion}`));
+  console.log();
+  console.log(pc.dim(`  Updated ${metadataPath}`));
+  console.log();
+}
+
 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.7",
+  "version": "1.0.9",
   "description": "CLI tool to scaffold Better Lyrics themes",
   "type": "module",
   "bin": {