create-bl-theme 1.0.9 → 1.0.11

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

@@ -170,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",
@@ -254,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();
@@ -365,6 +394,11 @@ MIT
 `;
   fs.writeFileSync(path.join(fullPath, "README.md"), readme);
 
+  fs.writeFileSync(
+    path.join(fullPath, ".gitattributes"),
+    "*.rics linguist-language=SCSS\n"
+  );
+
   // Create placeholder image note
   fs.writeFileSync(
     path.join(fullPath, "images", ".gitkeep"),
@@ -375,12 +409,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++;

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "create-bl-theme",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "CLI tool to scaffold Better Lyrics themes",
   "type": "module",
   "bin": {
     "create-bl-theme": "bin/cli.js"
   },
+  "files": [
+    "bin",
+    "templates"
+  ],
   "scripts": {
     "start": "node bin/cli.js"
   },

package/.claude/settings.local.json

@@ -1,12 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "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

@@ -1,73 +0,0 @@
-# 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/PLAN.md

@@ -1,399 +0,0 @@
-# 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)