exb-community-cli 1.0.0

package/README.md

@@ -0,0 +1,3 @@
+# 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.

package/dist/commands/install.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installWidget = installWidget;
+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 npm_1 = require("../utils/npm");
+async function installWidget(packageName, options = {}) {
+    const rootDir = process.cwd();
+    const tempDir = path_1.default.join(os_1.default.tmpdir(), `exb-install-${Date.now()}`);
+    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 {
+        console.log(`Fetching ${packageName}...`);
+        await pacote_1.default.extract(packageName, tempDir);
+        const { pkgContentPath, manifestPath } = await resolveManifest(tempDir);
+        // Using our interface for type safety
+        const manifest = await fs_extra_1.default.readJson(manifestPath);
+        const finalDestination = path_1.default.join(extensionsDir, manifest.name);
+        if (fs_extra_1.default.existsSync(finalDestination)) {
+            await fs_extra_1.default.remove(finalDestination);
+        }
+        await fs_extra_1.default.move(pkgContentPath, finalDestination);
+        console.log(`Installed ${manifest.name} successfully!`);
+        await (0, npm_1.runNpmCi)(finalDestination, { skip: options.widgetOnly });
+    }
+    catch (err) {
+        console.error(`Error: Failed to install widget: ${err.message}`);
+    }
+    finally {
+        await fs_extra_1.default.remove(tempDir);
+    }
+}
+async function resolveManifest(tempDir) {
+    const directManifest = path_1.default.join(tempDir, 'manifest.json');
+    const nestedManifest = path_1.default.join(tempDir, 'package', 'manifest.json');
+    if (await fs_extra_1.default.pathExists(directManifest)) {
+        return { pkgContentPath: tempDir, manifestPath: directManifest };
+    }
+    if (await fs_extra_1.default.pathExists(nestedManifest)) {
+        return { pkgContentPath: path_1.default.join(tempDir, 'package'), manifestPath: nestedManifest };
+    }
+    throw new Error('Invalid ExB widget: missing manifest.json');
+}

package/dist/commands/search.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchWidgets = searchWidgets;
+const https_1 = __importDefault(require("https"));
+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_SIZE = 15;
+async function searchWidgets(options = {}) {
+    if (options.githubList) {
+        console.log('GitHub list search is not yet implemented; falling back to npm search.');
+    }
+    const keywords = options.keyword ? [options.keyword] : DEFAULT_KEYWORDS;
+    const size = options.size ?? DEFAULT_SIZE;
+    let results = [];
+    try {
+        results = await searchNpm(keywords, size);
+    }
+    catch (err) {
+        console.error(`Failed to search npm: ${err.message}`);
+        return;
+    }
+    if (!results.length) {
+        console.log('No npm results found for the provided keywords.');
+        return;
+    }
+    const validated = [];
+    for (const pkg of results) {
+        const validatedPkg = await validateExbWidget(pkg.name, pkg.version);
+        if (validatedPkg) {
+            validated.push({ ...pkg, ...validatedPkg });
+        }
+    }
+    if (!validated.length) {
+        console.log('No valid Experience Builder widgets found in npm search results.');
+        return;
+    }
+    console.log(`Found ${validated.length} widget(s):`);
+    validated.forEach((pkg, idx) => {
+        const parts = [
+            `${idx + 1}. ${pkg.name}@${pkg.version}`,
+            pkg.label ? `label: ${pkg.label}` : undefined,
+            pkg.exbVersion ? `exbVersion: ${pkg.exbVersion}` : undefined,
+            pkg.description
+        ].filter(Boolean);
+        console.log(parts.join(' | '));
+    });
+}
+async function searchNpm(keywords, size) {
+    const text = keywords.map((k) => `keywords:${k}`).join(' ');
+    const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(text)}&size=${size}`;
+    const payload = await fetchJson(url);
+    if (!payload || !Array.isArray(payload.objects)) {
+        return [];
+    }
+    return payload.objects.map((obj) => ({
+        name: obj?.package?.name,
+        version: obj?.package?.version,
+        description: obj?.package?.description
+    })).filter((p) => Boolean(p.name && p.version));
+}
+async function validateExbWidget(pkgName, pkgVersion) {
+    const tempDir = path_1.default.join(os_1.default.tmpdir(), `exb-search-${pkgName.replace('/', '-')}-${Date.now()}`);
+    try {
+        await pacote_1.default.extract(`${pkgName}@${pkgVersion}`, tempDir);
+        const { manifestPath } = await resolveManifest(tempDir);
+        const manifest = await fs_extra_1.default.readJson(manifestPath);
+        if (manifest.type !== 'widget') {
+            return null;
+        }
+        return { exbVersion: manifest.exbVersion, label: manifest.label ?? manifest.name };
+    }
+    catch (err) {
+        return null;
+    }
+    finally {
+        await fs_extra_1.default.remove(tempDir);
+    }
+}
+async function resolveManifest(tempDir) {
+    const directManifest = path_1.default.join(tempDir, 'manifest.json');
+    const nestedManifest = path_1.default.join(tempDir, 'package', 'manifest.json');
+    if (await fs_extra_1.default.pathExists(directManifest)) {
+        return { pkgContentPath: tempDir, manifestPath: directManifest };
+    }
+    if (await fs_extra_1.default.pathExists(nestedManifest)) {
+        return { pkgContentPath: path_1.default.join(tempDir, 'package'), manifestPath: nestedManifest };
+    }
+    throw new Error('Invalid ExB widget: missing manifest.json');
+}
+async function fetchJson(url) {
+    return new Promise((resolve, reject) => {
+        const req = https_1.default.get(url, { headers: { 'User-Agent': 'exb-community-cli' } }, (res) => {
+            if (res.statusCode && res.statusCode >= 400) {
+                reject(new Error(`HTTP ${res.statusCode}`));
+                return;
+            }
+            let data = '';
+            res.on('data', (chunk) => { data += chunk; });
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        });
+        req.on('error', reject);
+    });
+}

package/dist/commands/update.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.updateWidget = updateWidget;
+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 semver_1 = __importDefault(require("semver"));
+const npm_1 = require("../utils/npm");
+async function updateWidget(packageName, options = {}) {
+    const rootDir = process.cwd();
+    const tempDir = path_1.default.join(os_1.default.tmpdir(), `exb-update-${Date.now()}`);
+    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;
+    }
+    const spec = options.version ? `${packageName}@${options.version}` : packageName;
+    try {
+        console.log(`Fetching ${spec}...`);
+        const incomingPkg = await pacote_1.default.manifest(spec);
+        await pacote_1.default.extract(spec, tempDir);
+        const { pkgContentPath, manifestPath: newManifestPath } = await resolveManifest(tempDir);
+        const newManifest = await fs_extra_1.default.readJson(newManifestPath);
+        const installedDir = path_1.default.join(extensionsDir, newManifest.name);
+        const installedManifestPath = path_1.default.join(installedDir, 'manifest.json');
+        const installedPkgJsonPath = path_1.default.join(installedDir, 'package.json');
+        if (!(await fs_extra_1.default.pathExists(installedManifestPath))) {
+            throw new Error(`Widget ${newManifest.name} is not installed; cannot update.`);
+        }
+        const currentManifest = await fs_extra_1.default.readJson(installedManifestPath);
+        const currentPkgJson = (await fs_extra_1.default.pathExists(installedPkgJsonPath)) ? await fs_extra_1.default.readJson(installedPkgJsonPath) : null;
+        const currentVersionRaw = currentPkgJson?.version ?? currentManifest.version;
+        const incomingVersionRaw = incomingPkg.version ?? newManifest.version;
+        const currentVersion = semver_1.default.valid(currentVersionRaw);
+        const incomingVersion = semver_1.default.valid(incomingVersionRaw);
+        if (!currentVersion || !incomingVersion) {
+            throw new Error('Unable to compare versions; expected valid semver from npm package metadata');
+        }
+        if (semver_1.default.eq(incomingVersion, currentVersion)) {
+            throw new Error(`Widget ${newManifest.name} is already at version ${currentVersionRaw}.`);
+        }
+        if (semver_1.default.lte(incomingVersion, currentVersion)) {
+            throw new Error(`New version ${incomingVersionRaw} is older than installed ${currentVersionRaw}.`);
+        }
+        await fs_extra_1.default.remove(installedDir);
+        await fs_extra_1.default.move(pkgContentPath, installedDir);
+        console.log(`Updated ${newManifest.name} to ${incomingVersionRaw}.`);
+        await (0, npm_1.runNpmCi)(installedDir, { skip: options.widgetOnly });
+    }
+    catch (err) {
+        console.error(`Error: Failed to update widget: ${err.message}`);
+    }
+    finally {
+        await fs_extra_1.default.remove(tempDir);
+    }
+}
+async function resolveManifest(tempDir) {
+    const directManifest = path_1.default.join(tempDir, 'manifest.json');
+    const nestedManifest = path_1.default.join(tempDir, 'package', 'manifest.json');
+    if (await fs_extra_1.default.pathExists(directManifest)) {
+        return { pkgContentPath: tempDir, manifestPath: directManifest };
+    }
+    if (await fs_extra_1.default.pathExists(nestedManifest)) {
+        return { pkgContentPath: path_1.default.join(tempDir, 'package'), manifestPath: nestedManifest };
+    }
+    throw new Error('Invalid ExB widget: missing manifest.json');
+}

package/dist/index.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+"use strict";
+// The line above is the "shebang". It MUST be the very first line of the file.
+// It tells the user's operating system to execute this file using Node.js.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const install_1 = require("./commands/install");
+const update_1 = require("./commands/update");
+const search_1 = require("./commands/search");
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const packageJsonPath = path.join(__dirname, '../package.json');
+const packageJson = fs.readJsonSync(packageJsonPath, { throws: false }) || { version: '1.0.0' };
+const program = new commander_1.Command();
+program
+    .name('exb-cli')
+    .description('The community-led widget manager for ArcGIS Experience Builder')
+    .version(packageJson.version);
+// --- COMMAND: INSTALL ---
+program
+    .command('install <package>')
+    .alias('i') // Allows users to type `exb-cli i widget-name`
+    .description('Install a widget from NPM into your Experience Builder project')
+    .option('--widget-only', 'Skip running npm ci in the installed widget directory')
+    .action(async (pkg, options) => {
+    await (0, install_1.installWidget)(pkg, { widgetOnly: options.widgetOnly });
+});
+// --- COMMAND: UPDATE ---
+program
+    .command('update <package>')
+    .alias('u')
+    .description('Update an installed widget to the latest version (or a specified version)')
+    .option('--widget-only', 'Skip running npm ci in the updated widget directory')
+    .option('--version <version>', 'Specify a version or dist-tag to update to')
+    .action(async (pkg, options) => {
+    await (0, update_1.updateWidget)(pkg, { widgetOnly: options.widgetOnly, version: options.version });
+});
+// --- COMMAND: LIST (Example for future expansion) ---
+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: SEARCH ---
+program
+    .command('search')
+    .alias('s')
+    .description('Search npm for Experience Builder widgets (by keyword)')
+    .option('-k, --keyword <keyword>', 'Additional keyword to include in search')
+    .option('-n, --size <size>', 'Maximum number of npm results to fetch (default: 15)')
+    .option('--github-list', 'Include results from a curated GitHub list when available')
+    .action(async (options) => {
+    const size = options.size ? Number(options.size) : undefined;
+    await (0, search_1.searchWidgets)({ keyword: options.keyword, size, githubList: options.githubList });
+});
+// 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
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+}

package/dist/utils/npm.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runNpmCi = runNpmCi;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+async function runNpmCi(widgetDir, options = {}) {
+    if (options.skip) {
+        console.log('Skipping npm ci because --widget-only was provided.');
+        return;
+    }
+    const shrinkwrap = path_1.default.join(widgetDir, 'npm-shrinkwrap.json');
+    const lockFile = path_1.default.join(widgetDir, 'package-lock.json');
+    const packageJson = path_1.default.join(widgetDir, 'package.json');
+    if (await fs_extra_1.default.pathExists(shrinkwrap)) {
+        await runNpm(widgetDir, ['ci'], 'npm-shrinkwrap.json found; running npm ci in widget directory...');
+        return;
+    }
+    if (await fs_extra_1.default.pathExists(lockFile)) {
+        await runNpm(widgetDir, ['ci'], 'Running npm ci in widget directory...');
+        return;
+    }
+    if (await fs_extra_1.default.pathExists(packageJson)) {
+        await runNpm(widgetDir, ['install'], 'No lockfile found; running npm install in widget directory...');
+        return;
+    }
+    console.log('No package.json found in widget; skipping dependency install.');
+}
+async function runNpm(cwd, args, startMessage) {
+    console.log(startMessage);
+    await new Promise((resolve, reject) => {
+        const proc = (0, child_process_1.spawn)('npm', args, {
+            cwd,
+            stdio: 'inherit',
+            shell: process.platform === 'win32'
+        });
+        proc.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`npm ${args.join(' ')} exited with code ${code}`));
+            }
+        });
+        proc.on('error', reject);
+    });
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "exb-community-cli",
+  "version": "1.0.0",
+  "description": "A lightweight command line interface to allow Experience Builder developers to quickly import widgets published as NPM pacakges.",
+  "keywords": [
+    "exb-community",
+    "cli",
+    "experience-builder",
+    "widget"
+  ],
+  "bin": {
+    "exb-cli": "dist/index.js"
+  },
+  "preferGlobal": true,
+  "license": "MIT",
+  "author": "Lucius Creamer",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "dependencies": {
+    "commander": "^14.0.3",
+    "fs-extra": "^11.3.3",
+    "pacote": "^21.3.1",
+    "semver": "^7.6.3"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.2.3",
+    "@types/pacote": "^11.1.8",
+    "@types/semver": "^7.5.8",
+    "typescript": "^5.9.3"
+  }
+}