exb-community-cli 1.0.0 → 1.0.1

package/README.md

@@ -1,3 +1,26 @@
 # ExB Community CLI
 
 A simple, lightweight command line interface to make using Experience Builder Developer Edition easier for new developers, looking to add widgets to their collection.
+
+## Using this CLI
+
+The ExB Community CLI has a few tools to make it easy to install, update, remove, and search for Experience Builder widgets that have been posted on NPM. Installing the CLI is as simple as running `npm i exb-community-cli` in your client directory of your Experience Builder application. To then run commands, the format is `npx exb-cli [command]`. If you don't want to prefix every command with npx, you can install the exb-community-cli globally, by running `npm i -g exb-community-cli`. For information on the commands that exist, run `npx exb-cli help`, and commands, arguments, and descriptions will be listed.
+
+When using any of the ExB Community CLI commands, the command needs to be run in the client directory of your Experience builder application. If you don't, you will get the error `Error: Run this from the ExB client folder.`.
+
+## Formatting widgets for NPM (And Best Practices)
+
+To prepare your widget to be easily ingested by the ExB Community CLI, there are a few key steps to take.
+
+1. Prepare your widget for NPM (Required)
+   - The ExB Community CLI has a format tool, which you can use to quickly prepare your widget for publication, if it doesn't already have a package.json file. Before running this command, ensure your manifest.json file has been filled out completely.
+   - If you are already using node in your widget (For using external libraries in your widget), ensure that the name in your package.json file is unique on NPM, and that the description is accurate. Also, please add the "exb-widget" keyword to your package.json file, to ensure that your widget can be easily found via the CLI.
+2. Ensure your widget has a README.md file at the root, with a description of how it functions, how to use it, and who built it. If you have demo applications, add links to those demo applications!
+3. Use a meaningful icon.svg. It's a small touch, but having a meaningful icon for other builders makes it much easier to build with.
+4. Add a help document to your widget. Again, another really small touch, but having a help document for users to be able to open up and get a walkthrough of how to use the widget in practice really does help, beyond providing a README.md file. To prevent from reinventing the wheel, if you already have a good README.md file, try converting it to an html file using [this free converter](https://www.netsmarter.com/md-to-html/).
+
+## Automation
+
+If you're like me, you probably don't want to re-publish your widget manually on NPM every time that you have an update. That'd be a pain right? Well, as long as you're using GitHub, I have a solution for you. _**GitHub Actions**_. You can use GitHub Actions to automate deployment to NPM using a fairly simple process, outlined in this [Esri Community Post](TBD).
+
+If you are using automated deployment YAML for your Experience Builder installs, you might also want to make sure that the widgets you're using come along for the ride. This CLI has that in mind! To inline install a widget into your build pipeline, use `npx exb-community-cli i widgetname`. This will install the widget into your project. If you want to ensure that you always use the same version of the widget, simply add the version suffix ex `@1.5.3`.

package/dist/commands/format.js

@@ -0,0 +1,199 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatWidget = formatWidget;
+exports.isNameAvailable = isNameAvailable;
+exports.suggestExbName = suggestExbName;
+exports.makeUniqueName = makeUniqueName;
+exports.validateAndChooseName = validateAndChooseName;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const readline_1 = __importDefault(require("readline"));
+const pacote_1 = __importDefault(require("pacote"));
+const validate_npm_package_name_1 = __importDefault(require("validate-npm-package-name"));
+async function formatWidget(widgetNameOrFolder, options = {}) {
+    const rootDir = process.cwd();
+    const widgetsDir = path_1.default.join(rootDir, 'your-extensions', 'widgets');
+    if (!fs_extra_1.default.existsSync(path_1.default.join(rootDir, 'your-extensions'))) {
+        console.error('Error: Run this from the ExB client folder.');
+        return;
+    }
+    if (!(await fs_extra_1.default.pathExists(widgetsDir))) {
+        console.error('Error: No widgets folder found (your-extensions/widgets).');
+        return;
+    }
+    // Find the widget folder by manifest.name or folder name
+    const candidates = await fs_extra_1.default.readdir(widgetsDir);
+    let widgetFolder = null;
+    let manifest = null;
+    for (const folder of candidates) {
+        const manifestPath = path_1.default.join(widgetsDir, folder, 'manifest.json');
+        if (await fs_extra_1.default.pathExists(manifestPath)) {
+            try {
+                const m = await fs_extra_1.default.readJson(manifestPath);
+                if (m && (m.name.toLowerCase() === widgetNameOrFolder.toLowerCase() || folder.toLowerCase() === widgetNameOrFolder.toLowerCase())) {
+                    widgetFolder = path_1.default.join(widgetsDir, folder);
+                    manifest = m;
+                    break;
+                }
+            }
+            catch (err) {
+                console.warn(`Warning: Failed to read manifest.json for widget candidate '${folder}': ${err.message || err}`);
+            }
+        }
+    }
+    if (!widgetFolder || !manifest) {
+        console.error(`Error: widget '${widgetNameOrFolder}' not found in your-extensions/widgets`);
+        return;
+    }
+    const pkgPath = path_1.default.join(widgetFolder, 'package.json');
+    const pkgExists = await fs_extra_1.default.pathExists(pkgPath);
+    if (pkgExists && !options.force) {
+        const proceed = await confirmPrompt(`package.json already exists for '${widgetNameOrFolder}' and will be modified. Proceed? (y/n)`);
+        if (!proceed) {
+            console.log('Aborted — package.json left unchanged.');
+            return;
+        }
+    }
+    // Collect package.json fields from manifest or prompt for missing values
+    const pkg = {};
+    const initialName = (manifest.name ?? (await askForValue('package name (npm-safe)'))) || '';
+    pkg.name = await validateAndChooseName(initialName, options.force);
+    pkg.version = (await askForValue('version', '1.0.0')) || '1.0.0';
+    pkg.description = manifest.description ?? (await askForValue('description')) ?? '';
+    pkg.author = manifest.author ?? (await askForValue('author')) ?? '';
+    pkg.license = manifest.license ?? (await askForValue('license', 'MIT')) ?? 'MIT';
+    pkg.keywords = ['exb-widget', 'experience-builder', 'exb'];
+    // Backup existing package.json
+    if (pkgExists) {
+        const backupPath = pkgPath + `.bak-${Date.now()}`;
+        await fs_extra_1.default.copy(pkgPath, backupPath);
+        console.log(`Existing package.json backed up to ${path_1.default.basename(backupPath)}`);
+    }
+    // Write package.json
+    await fs_extra_1.default.writeJson(pkgPath, pkg, { spaces: 2 });
+    console.log(`Wrote package.json for widget '${widgetNameOrFolder}' (version ${pkg.version}).`);
+}
+async function askForValue(promptText, defaultValue) {
+    const rl = readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    const question = defaultValue ? `${promptText} [${defaultValue}]: ` : `${promptText}: `;
+    const answer = await new Promise((resolve) => rl.question(question, resolve));
+    rl.close();
+    const val = (answer || defaultValue || '').trim();
+    return val === '' ? undefined : val;
+}
+async function confirmPrompt(message) {
+    const rl = readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(message + ' ', resolve));
+    rl.close();
+    const input = (answer || '').trim().toLowerCase();
+    return input === 'y' || input === 'yes';
+}
+async function isNameAvailable(name) {
+    try {
+        // If pacote.packument resolves, the package exists on the registry => not available
+        await pacote_1.default.packument(name);
+        return false;
+    }
+    catch (err) {
+        // pkg not found (404) -> available; other errors -> rethrow
+        const status = err && (err.statusCode || err.status);
+        if (status === 404)
+            return true;
+        // Some registries return different messages — treat any 404-like as available
+        if (/404|not found/i.test(String(err && err.message)))
+            return true;
+        throw err;
+    }
+}
+function suggestExbName(name) {
+    // preserve scope if present
+    if (name.startsWith('@')) {
+        const parts = name.split('/');
+        const scope = parts[0];
+        const pkg = parts[1] || '';
+        return `${scope}/exb-${pkg}`;
+    }
+    return `exb-${name}`;
+}
+async function makeUniqueName(base) {
+    // append numeric suffix until available
+    let attempt = base;
+    let i = 1;
+    while (!(await isNameAvailable(attempt))) {
+        attempt = `${base}-${i}`;
+        i += 1;
+        if (i > 1000)
+            throw new Error('Unable to find an available package name');
+    }
+    return attempt;
+}
+async function validateAndChooseName(initial, force = false) {
+    let name = (initial || '').trim();
+    // keep prompting until valid & available
+    while (true) {
+        // validate format
+        const res = (0, validate_npm_package_name_1.default)(name || '');
+        if (!res.validForNewPackages) {
+            if (force) {
+                // try to coerce with exb- prefix
+                const suggested = suggestExbName(name || 'widget');
+                const validSuggested = (0, validate_npm_package_name_1.default)(suggested).validForNewPackages;
+                if (!validSuggested)
+                    throw new Error(`Provided package name '${name}' is invalid and couldn't be coerced`);
+                name = suggested;
+            }
+            else {
+                console.log(`Invalid npm package name: ${(res.errors || []).concat(res.warnings || []).join('; ')}`);
+                const entered = await askForValue('enter a valid package name (npm-safe)');
+                if (!entered)
+                    throw new Error('Package name required');
+                name = entered.trim();
+                continue;
+            }
+        }
+        // check availability
+        try {
+            const available = await isNameAvailable(name);
+            if (available)
+                return name;
+            // name taken
+            const suggested = suggestExbName(name);
+            if ((0, validate_npm_package_name_1.default)(suggested).validForNewPackages) {
+                if (force) {
+                    const unique = await makeUniqueName(suggested);
+                    return unique;
+                }
+                const useSuggested = await confirmPrompt(`Package name '${name}' is already taken on npm. Use suggested '${suggested}' instead? (y/n)`);
+                if (useSuggested) {
+                    const finalName = (await isNameAvailable(suggested)) ? suggested : await makeUniqueName(suggested);
+                    return finalName;
+                }
+                const entered = await askForValue('enter an alternative package name');
+                if (!entered)
+                    throw new Error('Package name required');
+                name = entered.trim();
+                continue;
+            }
+            else {
+                // suggested name invalid (rare)
+                if (force) {
+                    const unique = await makeUniqueName(name);
+                    return unique;
+                }
+                console.log(`Package name '${name}' is taken and automatic suggestion is invalid.`);
+                const entered = await askForValue('enter an alternative package name');
+                if (!entered)
+                    throw new Error('Package name required');
+                name = entered.trim();
+                continue;
+            }
+        }
+        catch (err) {
+            // network / registry error — surface message and abort
+            throw new Error(`Failed to check npm for package name availability: ${err.message || err}`);
+        }
+    }
+}

package/dist/commands/remove.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeWidget = removeWidget;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+async function removeWidget(nameOrPackage, options = {}) {
+    const rootDir = process.cwd();
+    const extensionsDir = path_1.default.join(rootDir, 'your-extensions', 'widgets');
+    if (!fs_extra_1.default.existsSync(path_1.default.join(rootDir, 'your-extensions'))) {
+        console.error('Error: Run this from the ExB client folder.');
+        return;
+    }
+    try {
+        const installedWidgets = await fs_extra_1.default.readdir(extensionsDir);
+        let targetWidgetDir = null;
+        for (const widget of installedWidgets) {
+            const manifestPath = path_1.default.join(extensionsDir, widget, 'manifest.json');
+            const pkgJsonPath = path_1.default.join(extensionsDir, widget, 'package.json');
+            if (await fs_extra_1.default.pathExists(manifestPath)) {
+                const manifest = await fs_extra_1.default.readJson(manifestPath);
+                const pkgJson = (await fs_extra_1.default.pathExists(pkgJsonPath)) ? await fs_extra_1.default.readJson(pkgJsonPath) : { name: manifest.name, version: manifest.version };
+                if (manifest.name === nameOrPackage || widget === nameOrPackage || pkgJson.name === nameOrPackage) {
+                    targetWidgetDir = path_1.default.join(extensionsDir, widget);
+                    break;
+                }
+            }
+        }
+        if (!targetWidgetDir) {
+            console.error(`Error: No installed widget found matching "${nameOrPackage}".`);
+            return;
+        }
+        if (!options.force) {
+            const confirm = await promptConfirmation(`Are you sure you want to remove the widget at ${targetWidgetDir}? (y/n)`);
+            if (!confirm) {
+                console.log('Aborting widget removal.');
+                return;
+            }
+        }
+        await fs_extra_1.default.remove(targetWidgetDir);
+        console.log(`Removed widget at ${targetWidgetDir} successfully!`);
+    }
+    catch (err) {
+        console.error(`Error: Failed to remove widget: ${err.message}`);
+    }
+}
+async function promptConfirmation(message) {
+    return new Promise((resolve) => {
+        process.stdout.write(message + ' ');
+        process.stdin.setEncoding('utf-8');
+        process.stdin.resume();
+        const onData = (data) => {
+            const input = data.trim().toLowerCase();
+            cleanup();
+            resolve(input === 'y' || input === 'yes');
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve(false);
+        };
+        function cleanup() {
+            process.stdin.pause();
+            process.stdin.removeListener('data', onData);
+            process.stdin.removeListener('end', onEnd);
+        }
+        process.stdin.once('data', onData);
+        process.stdin.once('end', onEnd);
+    });
+}

package/dist/commands/scaffold.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaffoldWidget = scaffoldWidget;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const degit_1 = __importDefault(require("degit"));
+const enquirer_1 = __importDefault(require("enquirer"));
+const manifestCollector_1 = require("../utils/manifestCollector");
+const format_1 = require("./format");
+async function scaffoldWidget(name) {
+    const repoSource = "Esri/arcgis-experience-builder-sdk-resources/widgets";
+    const tmpDir = path_1.default.join(os_1.default.tmpdir(), `exb-scaffold-${Date.now()}`);
+    await fs_extra_1.default.ensureDir(tmpDir);
+    try {
+        const emitter = (0, degit_1.default)(repoSource, { cache: false, force: true, verbose: false });
+        await emitter.clone(tmpDir);
+        // Collect manifests from each widgets directory and merge results
+        const manifestsMap = {};
+        const m = await (0, manifestCollector_1.collectManifests)(tmpDir);
+        Object.assign(manifestsMap, m);
+        const items = Object.entries(manifestsMap).map(([file, manifest]) => ({ file, manifest }));
+        if (!items.length) {
+            console.log('No widgets found in the widgets folders.');
+            return;
+        }
+        console.log(`Found ${items.length} widgets in SDK-resources:`);
+        const choices = items.map((it) => ({
+            name: it.file,
+            message: `${it.manifest.label ?? it.manifest.name} — ${it.manifest.description ?? ''}`,
+            value: it.file
+        }));
+        try {
+            console.clear();
+            // Create prompt, and get user input
+            const prompt = new enquirer_1.default.Select({ name: 'widget', message: 'Choose a widget to scaffold', choices, limit: 10 });
+            const chosenFile = await prompt.run();
+            // Find the chosen item and copy its folder to the target location
+            const chosen = items.find((i) => i.file === chosenFile);
+            const widgetFolder = chosen.file.replace("/manifest.json", "");
+            const targetPath = path_1.default.join(process.cwd(), 'your-extensions', 'widgets', name);
+            await fs_extra_1.default.copy(widgetFolder, targetPath);
+            const manifestPath = path_1.default.join(targetPath, 'manifest.json');
+            const manifest = await fs_extra_1.default.readJson(manifestPath);
+            manifest.name = await (0, format_1.validateAndChooseName)(name);
+            await fs_extra_1.default.writeJson(manifestPath, manifest, { spaces: 2 });
+            console.log(`${chosen.manifest.label ?? chosen.manifest.name} scaffolded to ${targetPath}`);
+        }
+        catch (err) {
+            console.log('No selection made or prompt cancelled.');
+        }
+    }
+    finally {
+        try {
+            await fs_extra_1.default.remove(tmpDir);
+        }
+        catch (e) {
+            console.warn(`Warning: failed to remove temporary directory ${tmpDir}: ${e.message}`);
+        }
+    }
+}

package/dist/commands/search.js

@@ -9,7 +9,7 @@ const pacote_1 = __importDefault(require("pacote"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
-const DEFAULT_KEYWORDS = ['arcgis-exb-widget', 'experience-builder-widget'];
+const DEFAULT_KEYWORDS = ['exb-widget', 'experience-builder'];
 const DEFAULT_SIZE = 15;
 async function searchWidgets(options = {}) {
     if (options.githubList) {

package/dist/index.js

@@ -40,6 +40,9 @@ const commander_1 = require("commander");
 const install_1 = require("./commands/install");
 const update_1 = require("./commands/update");
 const search_1 = require("./commands/search");
+const remove_1 = require("./commands/remove");
+const format_1 = require("./commands/format");
+const scaffold_1 = require("./commands/scaffold");
 const fs = __importStar(require("fs-extra"));
 const path = __importStar(require("path"));
 const packageJsonPath = path.join(__dirname, '../package.json');
@@ -68,14 +71,14 @@ program
     .action(async (pkg, options) => {
     await (0, update_1.updateWidget)(pkg, { widgetOnly: options.widgetOnly, version: options.version });
 });
-// --- COMMAND: LIST (Example for future expansion) ---
+// --- COMMAND: REMOVE ---
 program
-    .command('list')
-    .alias('ls')
-    .description('List all community widgets currently installed in your project')
-    .action(() => {
-    console.log('Listing widgets is not yet implemented, but coming soon!');
-    // Future logic: scan the client/your-extensions/widgets folder and print the names
+    .command('remove <package>')
+    .alias('rm')
+    .description('Remove an installed widget from your Experience Builder project')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .action(async (pkg, options) => {
+    await (0, remove_1.removeWidget)(pkg, { force: options.force });
 });
 // --- COMMAND: SEARCH ---
 program
@@ -89,6 +92,23 @@ program
     const size = options.size ? Number(options.size) : undefined;
     await (0, search_1.searchWidgets)({ keyword: options.keyword, size, githubList: options.githubList });
 });
+// --- COMMAND: FORMAT ---
+program
+    .command('format <widget>')
+    .alias('fmt')
+    .description('Format a widget package according to community standards, based on the manifest.json configuration.')
+    .option('-f, --force', 'Skip prompts and overwrite package.json if present')
+    .action(async (widget, options) => {
+    await (0, format_1.formatWidget)(widget, { force: options.force });
+});
+// --- COMMAND: SCAFFOLD ---
+program
+    .command('scaffold <name>')
+    .alias('new')
+    .description('Scaffold a new widget package with a manifest.json and package.json, using a template from the arcgis-experience-builder-sdk-resources repository.')
+    .action(async (name, options) => {
+    await (0, scaffold_1.scaffoldWidget)(name);
+});
 // Parse the arguments passed by the user in the terminal
 program.parse(process.argv);
 // If the user runs the CLI with no arguments, show the help menu

package/dist/utils/manifestCollector.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectManifests = collectManifests;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Recursively find all manifest.json files under `rootDir` and return a map
+ * from absolute manifest file path -> parsed ExBManifest object.
+ *
+ * - Skips files that cannot be parsed.
+ * - Ignores node_modules and .git directories by default.
+ */
+async function collectManifests(rootDir) {
+    const result = {};
+    async function walk(dir) {
+        const entries = await fs_extra_1.default.readdir(dir, { withFileTypes: true });
+        for (const e of entries) {
+            // skip common noisy folders
+            if (e.name === 'node_modules' || e.name === '.git')
+                continue;
+            const full = path_1.default.join(dir, e.name);
+            if (e.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            if (e.isFile() && e.name.toLowerCase() === 'manifest.json') {
+                try {
+                    const json = await fs_extra_1.default.readJson(full);
+                    // Only include objects that have at least a name or type field (best-effort)
+                    if (json && typeof json === 'object') {
+                        const manifest = {
+                            name: json.name,
+                            label: json.label,
+                            description: json.description,
+                            author: json.author,
+                            license: json.license
+                        };
+                        result[full] = manifest;
+                    }
+                }
+                catch (err) {
+                    // silently skip invalid JSON
+                }
+            }
+        }
+    }
+    await walk(rootDir);
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exb-community-cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A lightweight command line interface to allow Experience Builder developers to quickly import widgets published as NPM pacakges.",
   "keywords": [
     "exb-community",
@@ -16,7 +16,8 @@
   "author": "Lucius Creamer",
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "jest --colors --runInBand"
   },
   "files": [
     "dist/**/*"
@@ -25,13 +26,20 @@
     "commander": "^14.0.3",
     "fs-extra": "^11.3.3",
     "pacote": "^21.3.1",
-    "semver": "^7.6.3"
+    "semver": "^7.7.4",
+    "validate-npm-package-name": "^7.0.2",
+    "degit": "^2.8.0",
+    "enquirer": "^2.3.6"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
+    "@types/jest": "^30.0.0",
     "@types/node": "^25.2.3",
     "@types/pacote": "^11.1.8",
     "@types/semver": "^7.5.8",
+    "@types/validate-npm-package-name": "^4.0.2",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
     "typescript": "^5.9.3"
   }
 }