extension-create 2.1.2 → 2.2.1

package/README.md

@@ -9,45 +9,57 @@
 
 # extension-create
 
-> Scaffold a new [Extension.js](https://extension.js.org) project from a template.
-
-This package implements the logic Extension.js uses to scaffold a new extension project from a selected template.
-It performs, in order:
-
-- Create or reuse the target directory (and fail on conflicting files)
-- Import the selected template (local in dev, remote via Git in prod)
-- Write `package.json` metadata and add Extension.js scripts
-- Write `manifest.json` metadata
-- Initialize a Git repository
-- Write a `.gitignore`
-- Remove template-only test files
-- If the template is TypeScript-based, generate `extension-env.d.ts`
+The standalone extension creation engine from [Extension.js](https://github.com/extension-js/extension.js). It provides an intuitive API for programmatically creating browser extensions with support for multiple frameworks and templates.
 
 ## Installation
 
-```
+Install the package using your preferred package manager:
+
+```bash
+npm install extension-create
+# or
 pnpm add extension-create
+# or
+yarn add extension-create
 ```
 
-## Usage
+## Quick Start
 
-```js
+Create a new extension with a single function call:
+
+```javascript
 import {extensionCreate} from 'extension-create'
 
-async function createNewExtension () {
-  await extensionCreate(
-    projectName: /* string (required) */,
-    {
-      template: 'init', // or any template name (see /examples)
-      install: false,   // optionally run the package manager install step
-      cliVersion: '2.x' // used to pin the CLI when not in dev mode
-    }
-  )
-}
-
-createNewExtension()
+// Create a basic extension
+await extensionCreate('my-extension', {
+  template: 'init'
+})
+
+// Create a React extension and install its dependencies
+await extensionCreate('my-react-extension', {
+  template: 'react',
+  install: true
+})
 ```
 
+## API Reference
+
+### `extensionCreate(projectName, options)`
+
+Creates a new extension project with the specified configuration.
+
+#### Parameters
+
+- `projectName` (string, required) - The name of your extension project
+- `options` (object) - Configuration options
+  - `template` (string, optional) - Template name or URL. Defaults to `'init'`
+  - `install` (boolean, optional) - Whether to install dependencies. Defaults to `true`
+  - `cliVersion` (string, optional) - CLI version for package.json
+
+## Templates
+
+Templates are sourced from the public Examples repository. See the catalog at `https://github.com/extension-js/examples` and reference templates by name, e.g. `content`, `content-react`, `content-vue`, etc.
+
 ## License
 
 MIT (c) Cezar Augusto.

package/dist/module.js

@@ -49,12 +49,12 @@ function destinationNotWriteable(workingDir) {
 }
 async function directoryHasConflicts(projectPath, conflictingFiles) {
     const projectName = external_path_namespaceObject.basename(projectPath);
-    let message = `Conflict! Path to ${external_pintor_default().yellow(projectName)} includes conflicting files.\n`;
+    let message = `Conflict! Path to ${external_pintor_default().blue(projectName)} includes conflicting files.\n\n`;
     for (const file of conflictingFiles){
         const stats = await external_fs_namespaceObject.promises.lstat(external_path_namespaceObject.join(projectPath, file));
-        message += stats.isDirectory() ? `${external_pintor_default().gray('-')} ${external_pintor_default().yellow(file)}\n` : `${external_pintor_default().gray('-')} ${external_pintor_default().yellow(file)}\n`;
+        message += stats.isDirectory() ? `   ${external_pintor_default().yellow('-')} ${external_pintor_default().yellow(file)}\n` : `   ${external_pintor_default().yellow('-')} ${external_pintor_default().yellow(file)}\n`;
     }
-    message += `${external_pintor_default().red('You need to either rename/remove the files listed above, or choose a new directory name for your extension.')}\nPath to conflicting directory: ${external_pintor_default().underline(projectPath)}`;
+    message += `\n${external_pintor_default().red('You need to either rename/remove the files listed above, or choose a new directory name for your extension.')}\n\nPath to conflicting directory: ${external_pintor_default().underline(projectPath)}`;
     return message;
 }
 function noProjectName() {
@@ -87,10 +87,10 @@ async function successfullInstall(projectPath, projectName) {
             installCmd = 'pnpm install';
         }
     }
-    return `\u{1F9E9} - ${external_pintor_default().green('Success!')} Extension ${external_pintor_default().yellow(projectName)} created.\nNow ${external_pintor_default().blue('cd')} ${external_pintor_default().underline(relativePath)}\n${external_pintor_default().blue(installCmd)} to install dependencies\n${external_pintor_default().blue(command)} to open a new browser instance\nwith your extension installed, loaded, and enabled for development.\n${external_pintor_default().green('You are ready')}. Time to hack on your extension!`;
+    return `\u{1F9E9} - ${external_pintor_default().green('Success!')} Extension ${external_pintor_default().blue(projectName)} created.\n\nTo get started developing your extension, do the following:\n\n   1. ${external_pintor_default().blue('cd')} ${external_pintor_default().underline(relativePath)}\n   2. ${external_pintor_default().blue(installCmd)} to install dependencies\n   3. ${external_pintor_default().blue(command)} to open a new browser instance with your extension loaded\n\n${external_pintor_default().green('You are ready')}. Time to hack on your extension!\n`;
 }
 function startingNewExtension(projectName) {
-    return `\u{1F423} - Starting a new browser extension named ${external_pintor_default().yellow(projectName)}...`;
+    return `\u{1F423} - Starting a new browser extension named ${external_pintor_default().blue(projectName)}...`;
 }
 function checkingIfPathIsWriteable() {
     return `\u{1F91E} - Checking if destination path is writeable...`;
@@ -99,56 +99,56 @@ function scanningPossiblyConflictingFiles() {
     return "\uD83D\uDD0E - Scanning for potential conflicting files...";
 }
 function createDirectoryError(projectName, error) {
-    return `${external_pintor_default().red('ERROR')} Can't create directory ${external_pintor_default().yellow(projectName)}.\n${external_pintor_default().red(String(error))}`;
+    return `${external_pintor_default().red('ERROR')} Can't create directory ${external_pintor_default().blue(projectName)}.\n${external_pintor_default().red(String(error))}`;
 }
 function writingTypeDefinitions(projectName) {
-    return `\u{1F537} - Writing type definitions for ${external_pintor_default().yellow(projectName)}...`;
+    return `\u{1F537} - Writing type definitions for ${external_pintor_default().blue(projectName)}...`;
 }
 function writingTypeDefinitionsError(error) {
     return `${external_pintor_default().red('ERROR')} Failed to write the extension type definition.\n${external_pintor_default().red(String(error))}`;
 }
 function installingFromTemplate(projectName, templateName) {
-    if ('init' === templateName) return `\u{1F9F0} - Installing ${external_pintor_default().yellow(projectName)}...`;
-    return `\u{1F9F0} - Installing ${external_pintor_default().yellow(projectName)} from template ${external_pintor_default().yellow(templateName)}...`;
+    if ('init' === templateName) return `\u{1F9F0} - Installing ${external_pintor_default().blue(projectName)}...`;
+    return `\u{1F9F0} - Installing ${external_pintor_default().blue(projectName)} from template ${external_pintor_default().yellow(templateName)}...`;
 }
 function installingFromTemplateError(projectName, template, error) {
-    return `${external_pintor_default().red('ERROR')} Can't find template ${external_pintor_default().yellow(template)} for ${external_pintor_default().yellow(projectName)}.\n${external_pintor_default().red(String(error))}`;
+    return `${external_pintor_default().red('ERROR')} Can't find template ${external_pintor_default().yellow(template)} for ${external_pintor_default().blue(projectName)}.\n${external_pintor_default().red(String(error))}`;
 }
 function initializingGitForRepository(projectName) {
-    return `\u{1F332} - Initializing git repository for ${external_pintor_default().yellow(projectName)}...`;
+    return `\u{1F332} - Initializing git repository for ${external_pintor_default().blue(projectName)}...`;
 }
 function initializingGitForRepositoryFailed(gitCommand, gitArgs, code) {
-    return `${external_pintor_default().red('ERROR')} Command ${external_pintor_default().gray(gitCommand)} ${external_pintor_default().gray(gitArgs.join(' '))} failed.\n${external_pintor_default().red(`exit code ${external_pintor_default().gray(String(code))}`)}`;
+    return `${external_pintor_default().red('ERROR')} Command ${external_pintor_default().yellow(gitCommand)} ${external_pintor_default().yellow(gitArgs.join(' '))} failed.\n${external_pintor_default().red(`exit code ${external_pintor_default().yellow(String(code))}`)}`;
 }
 function initializingGitForRepositoryProcessError(projectName, error) {
-    return `${external_pintor_default().red('ERROR')} Child process error: Can't initialize ${external_pintor_default().gray('git')} for ${external_pintor_default().yellow(projectName)}.\n${external_pintor_default().red(String((null == error ? void 0 : error.message) || error))}`;
+    return `${external_pintor_default().red('ERROR')} Child process error: Can't initialize ${external_pintor_default().yellow('git')} for ${external_pintor_default().blue(projectName)}.\n${external_pintor_default().red(String((null == error ? void 0 : error.message) || error))}`;
 }
 function initializingGitForRepositoryError(projectName, error) {
-    return `${external_pintor_default().red('ERROR')} Can't initialize ${external_pintor_default().gray('git')} for ${external_pintor_default().yellow(projectName)}.\n${external_pintor_default().red(String((null == error ? void 0 : error.message) || error))}`;
+    return `${external_pintor_default().red('ERROR')} Can't initialize ${external_pintor_default().yellow('git')} for ${external_pintor_default().blue(projectName)}.\n${external_pintor_default().red(String((null == error ? void 0 : error.message) || error))}`;
 }
 function installingDependencies() {
     return "\uD83D\uDEE0  - Installing dependencies... (takes a moment)";
 }
 function installingDependenciesFailed(gitCommand, gitArgs, code) {
-    return `${external_pintor_default().red('ERROR')} Command ${external_pintor_default().gray(gitCommand)} ${external_pintor_default().gray(gitArgs.join(' '))} failed.\n${external_pintor_default().red(`exit code ${external_pintor_default().gray(String(code))}`)}`;
+    return `${external_pintor_default().red('ERROR')} Command ${external_pintor_default().yellow(gitCommand)} ${external_pintor_default().yellow(gitArgs.join(' '))} failed.\n${external_pintor_default().red(`exit code ${external_pintor_default().yellow(String(code))}`)}`;
 }
 function installingDependenciesProcessError(projectName, error) {
-    return `${external_pintor_default().red('ERROR')} Child process error: Can't install dependencies for ${external_pintor_default().yellow(projectName)}.\n${external_pintor_default().red(String(error))}`;
+    return `${external_pintor_default().red('ERROR')} Child process error: Can't install dependencies for ${external_pintor_default().blue(projectName)}.\n${external_pintor_default().red(String(error))}`;
 }
 function cantInstallDependencies(projectName, error) {
-    return `${external_pintor_default().red('ERROR')} Can't install dependencies for ${external_pintor_default().yellow(projectName)}.\n${external_pintor_default().red(String((null == error ? void 0 : error.message) || error))}`;
+    return `${external_pintor_default().red('ERROR')} Can't install dependencies for ${external_pintor_default().blue(projectName)}.\n${external_pintor_default().red(String((null == error ? void 0 : error.message) || error))}`;
 }
 function writingPackageJsonMetadata() {
     return `\u{1F4DD} - Writing ${external_pintor_default().yellow('package.json')} metadata...`;
 }
 function writingPackageJsonMetadataError(projectName, error) {
-    return `${external_pintor_default().red('ERROR')} Can't write ${external_pintor_default().yellow('package.json')} for ${external_pintor_default().yellow(projectName)}.\n${external_pintor_default().red(String(error))}`;
+    return `${external_pintor_default().red('ERROR')} Can't write ${external_pintor_default().yellow('package.json')} for ${external_pintor_default().blue(projectName)}.\n${external_pintor_default().red(String(error))}`;
 }
 function writingManifestJsonMetadata() {
     return `\u{1F4DC} - Writing ${external_pintor_default().yellow('manifest.json')} metadata...`;
 }
 function writingManifestJsonMetadataError(projectName, error) {
-    return `${external_pintor_default().red('ERROR')} Can't write ${external_pintor_default().yellow('manifest.json')} for ${external_pintor_default().yellow(projectName)}.\n${external_pintor_default().red(String(error))}`;
+    return `${external_pintor_default().red('ERROR')} Can't write ${external_pintor_default().yellow('manifest.json')} for ${external_pintor_default().blue(projectName)}.\n${external_pintor_default().red(String(error))}`;
 }
 function writingReadmeMetaData() {
     return `\u{1F4C4} - Writing ${external_pintor_default().yellow('README.md')} metadata...`;
@@ -157,10 +157,10 @@ function writingGitIgnore() {
     return `\u{1F648} - Writing ${external_pintor_default().yellow('.gitignore')} lines...`;
 }
 function writingReadmeMetaDataEError(projectName, error) {
-    return `${external_pintor_default().red('ERROR')} Can't write the ${external_pintor_default().yellow('README.md')} file for ${external_pintor_default().yellow(projectName)}.\n${external_pintor_default().red(String(error))}`;
+    return `${external_pintor_default().red('ERROR')} Can't write the ${external_pintor_default().yellow('README.md')} file for ${external_pintor_default().blue(projectName)}.\n${external_pintor_default().red(String(error))}`;
 }
 function folderExists(projectName) {
-    return `\u{1F91D} - Ensuring ${external_pintor_default().yellow(projectName)} folder exists...`;
+    return `\u{1F91D} - Ensuring ${external_pintor_default().blue(projectName)} folder exists...`;
 }
 function writingDirectoryError(error) {
     return `${external_pintor_default().red('ERROR')} Error while checking directory writability.\n${external_pintor_default().red(String(error))}`;
@@ -203,7 +203,16 @@ async function moveDirectoryContents(source, destination) {
         else if (entry.isSymbolicLink()) {
             const target = await promises_namespaceObject.readlink(sourcePath);
             await promises_namespaceObject.symlink(target, destPath);
-        } else await promises_namespaceObject.rename(sourcePath, destPath);
+        } else try {
+            await promises_namespaceObject.rename(sourcePath, destPath);
+        } catch (err) {
+            if (err && ('EXDEV' === err.code || 'EINVAL' === err.code)) {
+                await promises_namespaceObject.copyFile(sourcePath, destPath);
+                await promises_namespaceObject.rm(sourcePath, {
+                    force: true
+                });
+            } else throw err;
+        }
     }
     await promises_namespaceObject.rm(source, {
         recursive: true,
@@ -274,8 +283,7 @@ async function createDirectory(projectPath, projectName) {
             throw new Error(conflictMessage);
         }
     } catch (error) {
-        console.error(createDirectoryError(projectName, error));
-        throw error;
+        throw new Error(createDirectoryError(projectName, error));
     }
 }
 const external_os_namespaceObject = require("os");
@@ -308,8 +316,32 @@ async function importExternalTemplate(projectPath, projectName, template) {
             });
             const isHttp = /^https?:\/\//i.test(template);
             const isGithub = /^https?:\/\/github.com\//i.test(template);
+            async function withFilteredOutput(fn) {
+                const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+                const originalStderrWrite = process.stderr.write.bind(process.stderr);
+                const shouldFilter = (chunk)=>{
+                    var _chunk_toString;
+                    const s = 'string' == typeof chunk ? chunk : (null == chunk ? void 0 : null == (_chunk_toString = chunk.toString) ? void 0 : _chunk_toString.call(chunk)) ?? '';
+                    if (!s) return false;
+                    return /Using git version/i.test(s) || /GitHub API rate limit reached, continuing without connectivity check/i.test(s);
+                };
+                process.stdout.write = (chunk, ...args)=>{
+                    if (shouldFilter(chunk)) return true;
+                    return originalStdoutWrite(chunk, ...args);
+                };
+                process.stderr.write = (chunk, ...args)=>{
+                    if (shouldFilter(chunk)) return true;
+                    return originalStderrWrite(chunk, ...args);
+                };
+                try {
+                    return await fn();
+                } finally{
+                    process.stdout.write = originalStdoutWrite;
+                    process.stderr.write = originalStderrWrite;
+                }
+            }
             if (isGithub) {
-                await external_go_git_it_default()(template, tempPath, installingFromTemplate(projectName, templateName));
+                await withFilteredOutput(()=>external_go_git_it_default()(template, tempPath, installingFromTemplate(projectName, templateName)));
                 const candidates = await promises_namespaceObject.readdir(tempPath, {
                     withFileTypes: true
                 });
@@ -328,7 +360,7 @@ async function importExternalTemplate(projectPath, projectName, template) {
                 zip.extractAllTo(tempPath, true);
                 await moveDirectoryContents(tempPath, projectPath);
             } else {
-                await external_go_git_it_default()(templateUrl, tempPath, installingFromTemplate(projectName, templateName));
+                await withFilteredOutput(()=>external_go_git_it_default()(templateUrl, tempPath, installingFromTemplate(projectName, templateName)));
                 const srcPath = external_path_namespaceObject.join(tempPath, templateName);
                 await moveDirectoryContents(srcPath, projectPath);
             }

package/dist/test-template-init/README.md

@@ -0,0 +1,47 @@
+<a href="https://extension.js.org" target="_blank"><img src="https://img.shields.io/badge/Powered%20by%20%7C%20Extension.js-0971fe" alt="Powered by Extension.js" align="right" /></a>
+
+# init
+
+> A basic browser extension example built with Extension.js. Perfect starting point for developers learning browser extension development with modern tooling.
+
+What this example does in the scope of a browser extension. The description should
+describe for an audience of developers looking to use the example. Avoid jargon and
+use simple language.
+
+## Installation
+
+```bash
+npx extension@latest create <project-name> --template init
+cd <project-name>
+npm install
+```
+
+## Commands
+
+### dev
+
+Run the extension in development mode.
+
+```bash
+npx extension@latest dev
+```
+
+### build
+
+Build the extension for production.
+
+```bash
+npx extension@latest build
+```
+
+### Preview
+
+Preview the extension in the browser.
+
+```bash
+npx extension@latest preview
+```
+
+## Learn more
+
+Learn more about this and other examples at @https://extension.js.org/

package/dist/test-template-init/index.js

@@ -0,0 +1 @@
+console.log('test')

package/dist/test-template-init/manifest.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/chrome-manifest.json",
+  "manifest_version": 3,
+  "version": "0.0.1",
+  "name": "test-template-init",
+  "description": "A basic browser extension example built with Extension.js. Perfect starting point for developers learning browser extension development with modern tooling.",
+  "icons": {
+    "48": "images/extension_48.png"
+  },
+  "author": "Your Name"
+}

package/dist/test-template-init/package.json

@@ -0,0 +1,22 @@
+{
+  "private": true,
+  "name": "test-template-init",
+  "description": "A basic browser extension example built with Extension.js. Perfect starting point for developers learning browser extension development with modern tooling.",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "author": {
+    "name": "Your Name",
+    "email": "your@email.com",
+    "url": "https://yourwebsite.com"
+  },
+  "scripts": {
+    "dev": "extension dev",
+    "start": "extension start",
+    "build": "extension build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "extension": "^undefined"
+  }
+}

package/package.json

@@ -2,8 +2,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/cezaraugusto/extension.git",
-    "directory": "programs/create"
+    "url": "https://github.com/extension-js/create.git"
   },
   "engines": {
     "node": ">=18"
@@ -21,8 +20,8 @@
     "dist"
   ],
   "name": "extension-create",
-  "version": "2.1.2",
-  "description": "The create step of Extension.js",
+  "version": "2.2.1",
+  "description": "The standalone extension creation engine for Extension.js",
   "author": {
     "name": "Cezar Augusto",
     "email": "boss@cezaraugusto.net",
@@ -57,7 +56,7 @@
   ],
   "dependencies": {
     "adm-zip": "^0.5.12",
-    "axios": "^1.7.2",
+    "axios": "^1.12.0",
     "cross-spawn": "^7.0.6",
     "go-git-it": "^5.0.0",
     "package-manager-detector": "^0.2.7",
@@ -65,19 +64,29 @@
     "tiny-glob": "^0.2.9"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.29.6",
+    "@eslint/js": "^9.16.0",
     "@rslib/core": "^0.6.9",
+    "@types/adm-zip": "^0.5.6",
+    "@types/chrome": "^0.0.287",
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^22.10.1",
-    "@vitest/coverage-v8": "3.2.2",
+    "@types/webextension-polyfill": "0.12.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.16.0",
     "globals": "^15.13.0",
+    "prettier": "^3.4.2",
     "tsconfig": "*",
     "typescript": "5.7.2",
-    "vitest": "3.2.2"
+    "vitest": "^3.2.4",
+    "webextension-polyfill": "^0.12.0"
   },
   "scripts": {
     "clean": "rm -rf dist",
     "watch": "rslib build --watch",
     "compile": "rslib build",
+    "format": "prettier --write \"**/*.{ts,tsx,md,js,json}\"",
+    "lint": "eslint .",
     "pretest:create": "pnpm compile",
     "test:create": "vitest run",
     "test:coverage": "vitest run --coverage"