create-bl-theme 1.0.8 → 1.0.9

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/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];
@@ -617,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 {
@@ -701,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
@@ -766,7 +831,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.9",
   "description": "CLI tool to scaffold Better Lyrics themes",
   "type": "module",
   "bin": {