create-bl-theme 1.0.8 → 1.0.10

package/.claude/settings.local.json

@@ -2,7 +2,9 @@
   "permissions": {
     "allow": [
       "Bash(cat:*)",
-      "Bash(node /Users/boidu/Developer/create-bl-theme/bin/cli.js bump:*)"
+      "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

@@ -164,7 +164,7 @@ Better Lyrics supports **GitHub Flavored Markdown (GFM)** in DESCRIPTION.md, so
 
 ### 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:
+After your theme is registered, install the [Better Lyrics Harmonizer](https://github.com/apps/better-lyrics-harmonizer/installations/new) GitHub App on your repo. This enables automatic updates:
 
 1. Bump your version: `create-bl-theme bump patch`
 2. Commit and push

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,11 +22,78 @@ 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];
@@ -103,7 +170,28 @@ ${pc.bold("Documentation:")}
 `);
 }
 
+function isDirectoryEmpty(dirPath) {
+  const entries = fs.readdirSync(dirPath);
+  return entries.every((entry) => entry.startsWith("."));
+}
+
 async function create(targetDir) {
+  if (targetDir) {
+    const earlyPath = path.resolve(process.cwd(), targetDir);
+    if (fs.existsSync(earlyPath) && !isDirectoryEmpty(earlyPath)) {
+      const { proceed } = await prompts({
+        type: "confirm",
+        name: "proceed",
+        message: `Directory "${targetDir}" is not empty. Continue anyway? (files may be overwritten)`,
+        initial: false,
+      });
+      if (!proceed) {
+        console.log(pc.red("\nCancelled."));
+        process.exit(1);
+      }
+    }
+  }
+
   const questions = [
     {
       type: targetDir ? null : "text",
@@ -187,9 +275,17 @@ async function create(targetDir) {
   const dir = targetDir || response.directory;
   const fullPath = path.resolve(process.cwd(), dir);
 
-  if (fs.existsSync(fullPath)) {
-    console.log(pc.red(`\nError: Directory "${dir}" already exists.`));
-    process.exit(1);
+  if (!targetDir && fs.existsSync(fullPath) && !isDirectoryEmpty(fullPath)) {
+    const { proceed } = await prompts({
+      type: "confirm",
+      name: "proceed",
+      message: `Directory "${dir}" is not empty. Continue anyway? (files may be overwritten)`,
+      initial: false,
+    });
+    if (!proceed) {
+      console.log(pc.red("\nCancelled."));
+      process.exit(1);
+    }
   }
 
   console.log();
@@ -308,12 +404,17 @@ MIT
   console.log(pc.green("  Theme scaffolded successfully!"));
   console.log();
   console.log(pc.bold("  Next steps:"));
-  console.log(`  ${pc.dim("1.")} cd ${dir}`);
-  console.log(`  ${pc.dim("2.")} Edit ${pc.cyan("style.rics")} with your theme styles`);
+  let stepNum = 1;
+  if (dir !== ".") {
+    console.log(`  ${pc.dim(`${stepNum}.`)} cd ${dir}`);
+    stepNum++;
+  }
+  console.log(`  ${pc.dim(`${stepNum}.`)} Edit ${pc.cyan("style.rics")} with your theme styles`);
+  stepNum++;
   console.log(
-    `  ${pc.dim("3.")} Add a preview screenshot to ${pc.cyan("images/preview.png")}`
+    `  ${pc.dim(`${stepNum}.`)} Add a preview screenshot to ${pc.cyan("images/preview.png")}`
   );
-  let stepNum = 4;
+  stepNum++;
   if (response.useDescriptionFile) {
     console.log(`  ${pc.dim(`${stepNum}.`)} Edit ${pc.cyan("DESCRIPTION.md")} with your theme description`);
     stepNum++;
@@ -617,6 +718,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 {
@@ -701,30 +807,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
@@ -766,7 +865,8 @@ async function publish(dir) {
     }
   }
 
-  console.log();
+  // Prompt to install GitHub App for auto-updates
+  await promptGitHubAppInstall();
 }
 
 function checkIsGitRepo(themePath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bl-theme",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "CLI tool to scaffold Better Lyrics themes",
   "type": "module",
   "bin": {