chrome-ext-ci-cd 1.0.0

package/README.md

@@ -0,0 +1,198 @@
+# chrome-ext-ci-cd
+
+CLI toolkit for Chrome extension CI/CD: validate, version, package, and release.
+
+Zero runtime dependencies. Works with any Chrome extension project using Manifest V3.
+
+## Quick Start
+
+```bash
+npm install -D chrome-ext-ci-cd
+npx chrome-ext-ci-cd init
+npx chrome-ext-ci-cd release patch
+```
+
+`init` scaffolds a GitHub Actions workflow, `.extensionignore`, `.nvmrc`, and npm scripts into your project. `release` validates your manifest, bumps the version, packages a `.zip`, commits, tags, and pushes -- triggering CI.
+
+## Commands
+
+### validate
+
+Validate `manifest.json` for Chrome Web Store compatibility.
+
+```bash
+chrome-ext-ci-cd validate [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--manifest, -m <path>` | Path to manifest.json (default: `manifest.json`) |
+| `--help, -h` | Show help |
+
+**Checks:** MV3 compliance, version format, icon file existence, permissions audit (flags dangerous permissions), CSP safety (blocks `unsafe-eval`).
+
+**Exit codes:** `0` on success, `1` on validation errors. Warnings do not affect the exit code.
+
+```bash
+npx chrome-ext-ci-cd validate
+npx chrome-ext-ci-cd validate --manifest src/manifest.json
+```
+
+### package
+
+Package the extension directory into a `.zip` for distribution.
+
+```bash
+chrome-ext-ci-cd package [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--source <dir>` | Extension source directory (default: `.`) |
+| `--output <path>` | Output zip file path (default: `dist/extension.zip`) |
+| `--help, -h` | Show help |
+
+Respects `.extensionignore` patterns plus built-in default exclusions (node_modules, .git, tests, etc.). Reports file count and size. Warns above 50 MB (Chrome Web Store soft limit).
+
+```bash
+npx chrome-ext-ci-cd package
+npx chrome-ext-ci-cd package --source . --output dist/my-ext.zip
+```
+
+### bump
+
+Bump the version in `manifest.json`, create a git commit and annotated tag, and push.
+
+```bash
+chrome-ext-ci-cd bump <patch|minor|major|x.y.z> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Preview version change without making changes |
+| `--manifest, -m <path>` | Path to manifest.json (default: `manifest.json`) |
+| `--help, -h` | Show help |
+
+Updates both `manifest.json` and `package.json` (if present). Refuses to run if the working tree has uncommitted changes. `--dry-run` shows what would happen without modifying any files.
+
+```bash
+npx chrome-ext-ci-cd bump patch
+npx chrome-ext-ci-cd bump minor --dry-run
+npx chrome-ext-ci-cd bump 2.0.0
+```
+
+### release
+
+Run the full release pipeline: validate, bump, and package in sequence.
+
+```bash
+chrome-ext-ci-cd release <patch|minor|major> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Validate (real), bump (preview), skip package |
+| `--manifest, -m <path>` | Path to manifest.json (default: `manifest.json`) |
+| `--source <dir>` | Extension source directory (default: `.`) |
+| `--output <path>` | Output zip file path (default: `dist/extension.zip`) |
+| `--help, -h` | Show help |
+
+Stops on first failure with a descriptive error naming which step failed. `--dry-run` runs validation normally, shows the version bump preview, and skips packaging.
+
+```bash
+npx chrome-ext-ci-cd release patch
+npx chrome-ext-ci-cd release minor --dry-run
+npx chrome-ext-ci-cd release major --source src --output dist/ext.zip
+```
+
+### init
+
+Scaffold CI/CD files into your Chrome extension project.
+
+```bash
+chrome-ext-ci-cd init [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--force, -f` | Overwrite existing files |
+| `--help, -h` | Show help |
+
+**Creates:**
+- `.github/workflows/release.yml` -- GitHub Actions workflow for CI/CD
+- `.extensionignore` -- Patterns for files to exclude from the zip
+- `.nvmrc` -- Node version file
+
+**Injects npm scripts** into `package.json`:
+- `ext:validate` -- `chrome-ext-ci-cd validate`
+- `ext:package` -- `chrome-ext-ci-cd package`
+- `ext:release:patch` -- `chrome-ext-ci-cd release patch`
+- `ext:release:minor` -- `chrome-ext-ci-cd release minor`
+- `ext:release:major` -- `chrome-ext-ci-cd release major`
+
+Warns before overwriting existing files. Use `--force` to overwrite.
+
+```bash
+npx chrome-ext-ci-cd init
+npx chrome-ext-ci-cd init --force
+```
+
+## Manual Setup
+
+If you prefer not to use `init`, create these files manually:
+
+### 1. GitHub Actions Workflow
+
+Create `.github/workflows/release.yml`. The workflow should trigger on version tags (`v*`) and PRs to `main`, with jobs for validation, packaging, GitHub Release creation, and optional Chrome Web Store publishing. See the [template](templates/release.yml) for a complete example.
+
+### 2. Extension Ignore
+
+Create `.extensionignore` in your project root with patterns for files to exclude from the extension zip:
+
+```
+.vscode/
+.idea/
+docs/
+*.md
+webpack.config.*
+*.psd
+*.sketch
+```
+
+Built-in defaults (node_modules, .git, tests, etc.) are always excluded regardless of this file.
+
+### 3. npm Scripts
+
+Add these scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "ext:validate": "chrome-ext-ci-cd validate",
+    "ext:package": "chrome-ext-ci-cd package",
+    "ext:release:patch": "chrome-ext-ci-cd release patch",
+    "ext:release:minor": "chrome-ext-ci-cd release minor",
+    "ext:release:major": "chrome-ext-ci-cd release major"
+  }
+}
+```
+
+## Requirements
+
+- **Node.js** 20 or later
+- **git** (for bump and release commands)
+- **zip** (for packaging -- pre-installed on most systems)
+
+## License
+
+Proprietary. All rights reserved.

package/bin/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+'use strict';
+
+const { version } = require('../package.json');
+const license = require('../lib/license');
+
+const COMMANDS = {
+  validate: { module: '../lib/validate', description: 'Validate manifest.json' },
+  package:  { module: '../lib/package',  description: 'Package extension as .zip' },
+  bump:     { module: '../lib/bump',     description: 'Bump version in manifest.json' },
+  release:  { module: '../lib/release',  description: 'Full release pipeline (validate + bump + package)' },
+  init:     { module: '../lib/init',     description: 'Scaffold CI/CD into your project' },
+  activate: { module: '../lib/activate', description: 'Activate a license key' },
+  keygen:   { module: '../lib/keygen',   description: 'Generate a license key (owner-only)' },
+};
+
+function printHelp() {
+  console.log(`chrome-ext-ci-cd v${version}`);
+  console.log('');
+  console.log('Usage: chrome-ext-ci-cd <command> [options]');
+  console.log('');
+  console.log('Commands:');
+  for (const [name, cmd] of Object.entries(COMMANDS)) {
+    console.log(`  ${name.padEnd(12)}${cmd.description}`);
+  }
+  console.log('');
+  console.log('Options:');
+  console.log('  --help, -h      Show this help message');
+  console.log('  --version, -v   Show version number');
+  console.log('');
+  console.log("Run 'chrome-ext-ci-cd <command> --help' for command-specific help.");
+}
+
+const arg = process.argv[2];
+
+if (!arg || arg === '--help' || arg === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+if (arg === '--version' || arg === '-v') {
+  console.log(version);
+  process.exit(0);
+}
+
+if (!COMMANDS[arg]) {
+  console.error(`Unknown command: ${arg}`);
+  console.error('');
+  printHelp();
+  process.exit(1);
+}
+
+// --- License Gate ---
+if (arg !== 'activate' && arg !== 'keygen') {
+  var licenseResult = license.checkLicense();
+  if (!licenseResult.valid) {
+    console.error(licenseResult.message);
+    process.exit(1);
+  }
+  if (licenseResult.trial) {
+    console.error('Trial: ' + licenseResult.daysLeft + ' day' + (licenseResult.daysLeft !== 1 ? 's' : '') + ' remaining. Activate a license: chrome-ext-ci-cd activate <key>');
+    console.error('');
+  }
+}
+
+const cmd = require(COMMANDS[arg].module);
+process.exitCode = cmd.run(process.argv.slice(3));

package/lib/activate.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseArgs } = require('node:util');
+const license = require('./license');
+
+// --- Help ---
+
+function printHelp() {
+  console.log('Usage: chrome-ext-ci-cd activate <key>');
+  console.log('');
+  console.log('Activate a license key for this machine.');
+  console.log('');
+  console.log('Arguments:');
+  console.log('  key                   The license key (starts with CECICD-)');
+  console.log('');
+  console.log('Options:');
+  console.log('  --help, -h            Show this help message');
+  console.log('');
+  console.log('Examples:');
+  console.log('  chrome-ext-ci-cd activate CECICD-eyJ0aWV....-a1b2c3d4...');
+}
+
+// --- CLI Runner ---
+
+function run(args) {
+  var values;
+  var positionals;
+  try {
+    var parsed = parseArgs({
+      args: args,
+      options: {
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      allowPositionals: true,
+    });
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (err) {
+    if (err.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
+      console.error('Unknown option: ' + err.message);
+      console.error('');
+      printHelp();
+      return 1;
+    }
+    throw err;
+  }
+
+  if (values.help) {
+    printHelp();
+    return 0;
+  }
+
+  // Get key from positionals
+  var key = positionals[0];
+  if (!key) {
+    console.error('Missing license key. Usage: chrome-ext-ci-cd activate <key>');
+    return 1;
+  }
+
+  // Validate key format and signature
+  var result = license.verifyKey(key, license.HMAC_SECRET);
+
+  if (!result.valid && result.expired) {
+    console.error('License key is expired (valid until ' + result.payload.exp + ').');
+    console.error('Contact the vendor for a renewal key.');
+    return 1;
+  }
+
+  if (!result.valid) {
+    console.error('Invalid license key: ' + result.error);
+    console.error('');
+    console.error('Check the key and try again:');
+    console.error('  chrome-ext-ci-cd activate <key>');
+    return 1;
+  }
+
+  // Store the key
+  var configDir = license.getConfigDir();
+  fs.mkdirSync(configDir, { recursive: true });
+  var licensePath = path.join(configDir, 'license');
+  fs.writeFileSync(licensePath, key + '\n');
+
+  // Print activation summary
+  console.log('License activated successfully.');
+  console.log('');
+  console.log('  Customer:  ' + result.payload.customer);
+  console.log('  Tier:      ' + result.payload.tier);
+  console.log('  Expires:   ' + result.payload.exp);
+  console.log('  Stored at: ' + licensePath);
+
+  return 0;
+}
+
+// --- Exports ---
+
+module.exports = { run: run };

package/lib/bump.js

@@ -0,0 +1,299 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { parseArgs } = require('node:util');
+
+// --- Helpers ---
+
+function calculateNewVersion(currentVersion, bumpType) {
+  if (['patch', 'minor', 'major'].includes(bumpType)) {
+    var parts = currentVersion.split('.').map(Number);
+    // Pad to 3 parts if needed
+    while (parts.length < 3) parts.push(0);
+
+    switch (bumpType) {
+      case 'major':
+        parts[0]++;
+        parts[1] = 0;
+        parts[2] = 0;
+        break;
+      case 'minor':
+        parts[1]++;
+        parts[2] = 0;
+        break;
+      case 'patch':
+        parts[2]++;
+        break;
+    }
+    return parts.join('.');
+  }
+  // Explicit version provided
+  return bumpType;
+}
+
+function checkDirtyTree() {
+  try {
+    execFileSync('git', ['diff', '--quiet'], { stdio: 'pipe' });
+    execFileSync('git', ['diff', '--cached', '--quiet'], { stdio: 'pipe' });
+    return { clean: true };
+  } catch (e) {
+    return {
+      clean: false,
+      message: 'Working tree has uncommitted changes. Commit or stash changes first.'
+    };
+  }
+}
+
+// --- Pure Bump Function ---
+
+function bump(bumpType, options) {
+  var opts = options || {};
+
+  // Validate bumpType
+  if (!bumpType) {
+    return {
+      success: false,
+      errors: ['Bump type required. Use: patch, minor, major, or an explicit version (e.g., 2.1.0)'],
+      warnings: [],
+      data: {}
+    };
+  }
+
+  // Resolve manifest path
+  var manifestPath = path.resolve(
+    opts.manifestPath || opts.manifest || process.env.MANIFEST_PATH || path.join(process.cwd(), 'manifest.json')
+  );
+
+  var data = { manifestPath: manifestPath };
+
+  // Check manifest exists
+  if (!fs.existsSync(manifestPath)) {
+    return {
+      success: false,
+      errors: ['Manifest not found: ' + manifestPath + '. Check the file path or use --manifest to specify location.'],
+      warnings: [],
+      data: data
+    };
+  }
+
+  // Read and parse manifest
+  var manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch (e) {
+    return {
+      success: false,
+      errors: ['Invalid JSON in ' + manifestPath + ': ' + e.message],
+      warnings: [],
+      data: data
+    };
+  }
+
+  // Get current version
+  var currentVersion = manifest.version;
+  if (!currentVersion) {
+    return {
+      success: false,
+      errors: ['manifest.json is missing "version" field.'],
+      warnings: [],
+      data: data
+    };
+  }
+
+  // Calculate new version
+  var newVersion = calculateNewVersion(currentVersion, bumpType);
+  var tag = 'v' + newVersion;
+
+  data.previousVersion = currentVersion;
+  data.newVersion = newVersion;
+  data.tag = tag;
+
+  // Dry run -- return early without side effects
+  if (opts.dryRun) {
+    data.dryRun = true;
+    return {
+      success: true,
+      errors: [],
+      warnings: [],
+      data: data
+    };
+  }
+
+  // Check dirty tree
+  var treeStatus = checkDirtyTree();
+  if (!treeStatus.clean) {
+    return {
+      success: false,
+      errors: [treeStatus.message],
+      warnings: [],
+      data: data
+    };
+  }
+
+  // Update manifest.json
+  manifest.version = newVersion;
+  if (manifest.version_name !== undefined) {
+    manifest.version_name = newVersion;
+  }
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+
+  // Update package.json in the same directory (D-05: bump always syncs both)
+  var packageJsonPath = path.join(path.dirname(manifestPath), 'package.json');
+  var updatedPackageJson = false;
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      var pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+      pkg.version = newVersion;
+      fs.writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n');
+      updatedPackageJson = true;
+    } catch (e) {
+      // Skip silently if package.json can't be parsed
+    }
+  }
+
+  // Git operations
+  try {
+    // Stage manifest.json (always)
+    execFileSync('git', ['add', manifestPath], { stdio: 'pipe' });
+
+    // Stage package.json only if it was updated
+    if (updatedPackageJson) {
+      execFileSync('git', ['add', packageJsonPath], { stdio: 'pipe' });
+    }
+
+    // Commit
+    execFileSync('git', ['commit', '-m', 'chore: bump version to ' + newVersion], { stdio: 'pipe' });
+
+    // Tag (annotated)
+    execFileSync('git', ['tag', '-a', tag, '-m', 'Release ' + tag], { stdio: 'pipe' });
+  } catch (e) {
+    var errMsg = e.stderr ? e.stderr.toString() : e.message;
+    return {
+      success: false,
+      errors: ['Git operations failed: ' + errMsg + '. Commit and tag were not created.'],
+      warnings: [],
+      data: data
+    };
+  }
+
+  // Push
+  try {
+    var branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      encoding: 'utf-8'
+    }).trim();
+
+    execFileSync('git', ['push', 'origin', branch, '--follow-tags'], { stdio: 'inherit' });
+    data.branch = branch;
+  } catch (e) {
+    return {
+      success: false,
+      errors: ['Push failed. You can push manually: git push origin --follow-tags'],
+      warnings: [],
+      data: data
+    };
+  }
+
+  return {
+    success: true,
+    errors: [],
+    warnings: [],
+    data: data
+  };
+}
+
+// --- Help ---
+
+function printHelp() {
+  console.log('Usage: chrome-ext-ci-cd bump <patch|minor|major|x.y.z> [options]');
+  console.log('');
+  console.log('Bump version in manifest.json, commit, tag, and push.');
+  console.log('');
+  console.log('Arguments:');
+  console.log('  patch             Increment patch version (1.0.0 -> 1.0.1)');
+  console.log('  minor             Increment minor version (1.0.0 -> 1.1.0)');
+  console.log('  major             Increment major version (1.0.0 -> 2.0.0)');
+  console.log('  x.y.z             Set explicit version');
+  console.log('');
+  console.log('Options:');
+  console.log('  --dry-run         Preview version change without making changes');
+  console.log('  --manifest, -m    Path to manifest.json (default: manifest.json)');
+  console.log('  --help, -h        Show this help message');
+  console.log('');
+  console.log('Examples:');
+  console.log('  chrome-ext-ci-cd bump patch');
+  console.log('  chrome-ext-ci-cd bump minor --dry-run');
+  console.log('  chrome-ext-ci-cd bump 2.0.0');
+}
+
+// --- CLI Runner ---
+
+function run(args) {
+  var values, positionals;
+  try {
+    var parsed = parseArgs({
+      args: args,
+      options: {
+        'dry-run': { type: 'boolean', default: false },
+        manifest: { type: 'string', short: 'm', default: process.env.MANIFEST_PATH || 'manifest.json' },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      allowPositionals: true,
+    });
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (err) {
+    if (err.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
+      console.error('Unknown option: ' + err.message);
+      console.error('');
+      printHelp();
+      return 1;
+    }
+    throw err;
+  }
+
+  if (values.help) {
+    printHelp();
+    return 0;
+  }
+
+  var bumpType = positionals[0];
+  if (!bumpType) {
+    console.error('Bump type required. Usage: chrome-ext-ci-cd bump <patch|minor|major> [--dry-run]');
+    return 1;
+  }
+
+  var result = bump(bumpType, {
+    manifestPath: path.resolve(values.manifest),
+    dryRun: values['dry-run']
+  });
+
+  // Format output
+  if (result.data.previousVersion) {
+    console.log('Current version: ' + result.data.previousVersion);
+  }
+  if (result.data.newVersion) {
+    console.log('New version:     ' + result.data.newVersion);
+  }
+
+  if (result.data.dryRun) {
+    console.log('');
+    console.log('[DRY RUN] No changes made.');
+  } else if (result.success) {
+    console.log('');
+    console.log('Created commit and tag: ' + result.data.tag);
+    if (result.data.branch) {
+      console.log('Pushed ' + result.data.branch + ' + ' + result.data.tag + ' to origin.');
+    }
+  }
+
+  if (result.errors.length > 0) {
+    console.log('');
+    result.errors.forEach(function(e) { console.error('ERROR: ' + e); });
+  }
+
+  return result.success ? 0 : 1;
+}
+
+module.exports = { bump, run };