exb-community-cli 1.0.1 → 1.0.2

package/README.md

@@ -4,9 +4,11 @@ A simple, lightweight command line interface to make using Experience Builder De
 
 ## 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.
+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` (Recommended). 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.`.
+Additionally, this CLI makes it easy to get up and running with Experience Builder, requiring a single command to install and run Experience Builder Developer Edition, making it easier than ever to get started. Just install the CLI globally `npm-i -g exb-community-cli` and then run `exb-cli dev-setup`. The tool will give you a few prompts to get started, and you'll end up with a fully functional install.
+
+When using any of the ExB Community CLI commands, the command needs to be run in the client directory of your Experience builder application (excluding dev-setup). If you don't, you will get the error `Error: Run this from the ExB client folder.`.
 
 ## Formatting widgets for NPM (And Best Practices)
 

package/dist/commands/dev-setup.js

@@ -0,0 +1,237 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.devSetup = devSetup;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const promises_1 = require("stream/promises");
+const fs_1 = require("fs");
+const child_process_1 = require("child_process");
+const readline_1 = require("readline");
+const enquirer_1 = __importDefault(require("enquirer"));
+const os_1 = __importDefault(require("os"));
+async function devSetup(options) {
+    let version = options.version;
+    const response = await fetch("https://developers.arcgis.com/experience-builder/guide/downloads/");
+    const html = await response.text();
+    // Extract version numbers from the page using a regex
+    const versions = [...html.matchAll(/py-4 pr-3">v(\d+\.\d+)/g)].map((m) => m[1]);
+    if (options.version && options.version == "latest") {
+        console.log("Setting up development environment for latest version...");
+        const latestVersion = versions[0];
+        version = latestVersion;
+    }
+    else if (options.version === undefined) {
+        const prompt = new enquirer_1.default.Select({
+            name: "version",
+            message: "Choose an Experience Builder version",
+            choices: versions,
+            limit: 5
+        });
+        const chosenVersion = await prompt.run();
+        version = chosenVersion;
+    }
+    // Actually install and set up the chosen version of Experience Builder
+    await installExperienceBuilder(version);
+    // Ask user if they want to start the development servers now
+    const approveStart = await new enquirer_1.default.Confirm({
+        name: "start",
+        message: "Do you want to start the development server now?"
+    }).run();
+    if (!approveStart) {
+        console.log("You can start the development server later by running `npm start` in the client and server folders.");
+        return;
+    }
+    const clientDir = path_1.default.join(process.cwd(), `arcgis-experience-builder-${version}`, "client");
+    const serverDir = path_1.default.join(process.cwd(), `arcgis-experience-builder-${version}`, "server");
+    console.log("Starting development servers in new terminal windows...");
+    openInNewTerminal(clientDir, "client");
+    openInNewTerminal(serverDir, "server");
+}
+const ciWithSpinner = (message, cwd) => {
+    const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    let frameIndex = 0;
+    return new Promise((resolve, reject) => {
+        const interval = setInterval(() => {
+            frameIndex = (frameIndex + 1) % spinnerFrames.length;
+            process.stdout.write(`\r  ${spinnerFrames[frameIndex]} ${message}`);
+        }, 80);
+        process.stdout.write(`  ${spinnerFrames[0]} ${message}`);
+        const proc = (0, child_process_1.spawn)("npm", ["ci"], { cwd, stdio: "pipe" });
+        proc.on("close", (code) => {
+            clearInterval(interval);
+            if (code === 0) {
+                process.stdout.write(`\r  ✔ ${message} done.\n`);
+                resolve();
+            }
+            else {
+                process.stdout.write(`\r  ✖ ${message} failed.\n`);
+                reject(new Error(`npm ci exited with code ${code}`));
+            }
+        });
+        proc.on("error", (err) => {
+            clearInterval(interval);
+            reject(err);
+        });
+    });
+};
+const openInNewTerminal = (cwd, label) => {
+    const cmd = `cd "${cwd}" && npm start`;
+    if (process.platform === "darwin") {
+        const script = `tell application "Terminal"\nactivate\ndo script "${cmd.replace(/"/g, '\\"')}"\nend tell`;
+        (0, child_process_1.spawn)("osascript", ["-e", script], {
+            stdio: "ignore",
+            detached: true
+        }).unref();
+    }
+    else if (process.platform === "win32") {
+        (0, child_process_1.spawn)("cmd.exe", ["/c", "start", "cmd.exe", "/k", cmd], {
+            cwd,
+            stdio: "ignore",
+            detached: true,
+            shell: true
+        }).unref();
+    }
+    else {
+        // Linux: try common terminal emulators in order
+        const terminals = [
+            {
+                bin: "x-terminal-emulator",
+                args: ["-e", `bash -c '${cmd}; exec bash'`]
+            },
+            {
+                bin: "gnome-terminal",
+                args: ["--", "bash", "-c", `${cmd}; exec bash`]
+            },
+            { bin: "konsole", args: ["-e", "bash", "-c", `${cmd}; exec bash`] },
+            {
+                bin: "xfce4-terminal",
+                args: ["-e", `bash -c '${cmd}; exec bash'`]
+            },
+            { bin: "xterm", args: ["-e", `bash -c '${cmd}; exec bash'`] }
+        ];
+        let launched = false;
+        for (const t of terminals) {
+            try {
+                (0, child_process_1.execSync)(`which ${t.bin}`, { stdio: "pipe" });
+                (0, child_process_1.spawn)(t.bin, t.args, {
+                    cwd,
+                    stdio: "ignore",
+                    detached: true
+                }).unref();
+                launched = true;
+                break;
+            }
+            catch {
+                // not found, try next
+            }
+        }
+        if (!launched) {
+            console.log(`  ⚠ No supported terminal found. Run manually: cd "${cwd}" && npm start`);
+            return;
+        }
+    }
+    console.log(`  ✔ Opened ${label} in a new terminal window.`);
+};
+const installExperienceBuilder = async (version) => {
+    const url = `https://downloads.arcgis.com/dms/rest/download/secured/arcgis-experience-builder-${version}.zip?f=json&folder=software%2FExperienceBuilder%2F${version}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch download info: ${res.status} ${res.statusText}`);
+    }
+    const json = (await res.json());
+    const downloadUrl = json.url;
+    if (!downloadUrl) {
+        throw new Error("No download URL found in response");
+    }
+    // Download the zip file to a temporary location
+    const zipPath = path_1.default.join(os_1.default.tmpdir(), `exb-install-${Date.now()}`);
+    const extractDir = path_1.default.resolve(process.cwd(), `arcgis-experience-builder-${version}`);
+    try {
+        console.log(`Downloading zip`);
+        const zipRes = await fetch(downloadUrl);
+        if (!zipRes.ok || !zipRes.body) {
+            throw new Error(`Failed to download zip: ${zipRes.status} ${zipRes.statusText}`);
+        }
+        await (0, promises_1.pipeline)(zipRes.body, (0, fs_1.createWriteStream)(zipPath));
+        // Extract the zip file to a folder in the current directory
+        console.log(`Extracting to ${extractDir}...`);
+        await fs_extra_1.default.ensureDir(extractDir);
+        // Get total file count for progress bar (pipe through tail to avoid buffer overflow on large zips)
+        const listSummary = (0, child_process_1.execSync)(`unzip -l "${zipPath}" | tail -1`, {
+            encoding: "utf-8"
+        });
+        const countMatch = listSummary.match(/(\d+)\s+files?/);
+        const totalFiles = countMatch ? parseInt(countMatch[1], 10) : 1;
+        await new Promise((resolve, reject) => {
+            let extracted = 0;
+            const proc = (0, child_process_1.spawn)("unzip", ["-o", zipPath, "-d", extractDir]);
+            const rl = (0, readline_1.createInterface)({ input: proc.stdout });
+            rl.on("line", (line) => {
+                if (/^\s*(extracting|inflating|creating):/.test(line)) {
+                    extracted++;
+                    const pct = Math.min(100, Math.round((extracted / totalFiles) * 100));
+                    const filled = Math.round(pct / 4);
+                    const bar = "█".repeat(filled) + "░".repeat(25 - filled);
+                    process.stdout.write(`\r  [${bar}] ${pct}% (${extracted}/${totalFiles})`);
+                }
+            });
+            proc.stderr.on("data", () => { }); // suppress stderr
+            proc.on("close", (code) => {
+                process.stdout.write("\n");
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`unzip exited with code ${code}`));
+            });
+            proc.on("error", reject);
+        });
+        // Remove any directory nesting (some zip versions include an extra top-level folder)
+        const entries = await fs_extra_1.default.readdir(extractDir);
+        const hasClient = entries.includes("client");
+        const hasServer = entries.includes("server");
+        if (!hasClient || !hasServer) {
+            // Check if there's a single nested directory containing client/ and server/
+            const dirs = [];
+            for (const entry of entries) {
+                const stat = await fs_extra_1.default.stat(path_1.default.join(extractDir, entry));
+                if (stat.isDirectory())
+                    dirs.push(entry);
+            }
+            if (dirs.length === 1) {
+                const nestedDir = path_1.default.join(extractDir, dirs[0]);
+                const nestedEntries = await fs_extra_1.default.readdir(nestedDir);
+                if (nestedEntries.includes("client") &&
+                    nestedEntries.includes("server")) {
+                    // Move all contents from the nested dir up to extractDir
+                    for (const item of nestedEntries) {
+                        await fs_extra_1.default.move(path_1.default.join(nestedDir, item), path_1.default.join(extractDir, item), { overwrite: true });
+                    }
+                    await fs_extra_1.default.remove(nestedDir);
+                }
+                else {
+                    throw new Error("Extracted zip does not contain expected client/ and server/ folders");
+                }
+            }
+            else {
+                throw new Error("Extracted zip does not contain expected client/ and server/ folders");
+            }
+        }
+        // Install dependencies in client and server folders
+        const clientDir = path_1.default.join(extractDir, "client");
+        const serverDir = path_1.default.join(extractDir, "server");
+        await ciWithSpinner("Installing client dependencies...", clientDir);
+        await ciWithSpinner("Installing server dependencies...", serverDir);
+        return extractDir;
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        return "";
+    }
+    finally {
+        // Clean up the zip file
+        await fs_extra_1.default.remove(zipPath);
+    }
+};

package/dist/commands/format.js

@@ -60,7 +60,7 @@ async function formatWidget(widgetNameOrFolder, options = {}) {
     // 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.name = await validateAndChooseName(initialName.toLowerCase(), 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')) ?? '';

package/dist/commands/scaffold.js

@@ -10,8 +10,17 @@ 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 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;
+    }
     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);
@@ -45,7 +54,8 @@ async function scaffoldWidget(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);
+            //manifest.name = await validateAndChooseName(name);
+            manifest.name = name;
             await fs_extra_1.default.writeJson(manifestPath, manifest, { spaces: 2 });
             console.log(`${chosen.manifest.label ?? chosen.manifest.name} scaffolded to ${targetPath}`);
         }

package/dist/index.js

@@ -45,70 +45,90 @@ 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');
-const packageJson = fs.readJsonSync(packageJsonPath, { throws: false }) || { version: '1.0.0' };
+const dev_setup_1 = require("./commands/dev-setup");
+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')
+    .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')
+    .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')
+    .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 });
+    await (0, update_1.updateWidget)(pkg, {
+        widgetOnly: options.widgetOnly,
+        version: options.version
+    });
 });
 // --- COMMAND: REMOVE ---
 program
-    .command('remove <package>')
-    .alias('rm')
-    .description('Remove an installed widget from your Experience Builder project')
-    .option('-f, --force', 'Skip confirmation prompt')
+    .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
-    .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')
+    .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 });
+    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')
+    .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.')
+    .command("scaffold <name>")
+    .alias("new")
+    .description("Scaffold a new widget package with a manifest.json, using an esri template")
     .action(async (name, options) => {
     await (0, scaffold_1.scaffoldWidget)(name);
 });
+program
+    .command("dev-setup")
+    .description("Download and set up the local development environment for Experience Builder widget development")
+    .option("--latest", "Download the latest version of Experience Builder Developer Edition")
+    .option("-v, --version <version>", "Specify a version of Experience Builder Developer Edition to download")
+    .action(async (options) => {
+    const version = options.version || (options.latest ? "latest" : undefined);
+    (0, dev_setup_1.devSetup)({ version });
+    //await scaffoldWidget('dev-environment', { version });
+});
 // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exb-community-cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A lightweight command line interface to allow Experience Builder developers to quickly import widgets published as NPM pacakges.",
   "keywords": [
     "exb-community",
@@ -24,12 +24,12 @@
   ],
   "dependencies": {
     "commander": "^14.0.3",
+    "degit": "^2.8.0",
+    "enquirer": "^2.3.6",
     "fs-extra": "^11.3.3",
     "pacote": "^21.3.1",
     "semver": "^7.7.4",
-    "validate-npm-package-name": "^7.0.2",
-    "degit": "^2.8.0",
-    "enquirer": "^2.3.6"
+    "validate-npm-package-name": "^7.0.2"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
@@ -42,4 +42,4 @@
     "ts-jest": "^29.1.0",
     "typescript": "^5.9.3"
   }
-}
+}