@magnolia/cli-jumpstart-plugin 1.0.0-preview.6 → 1.0.0-preview.7

package/README.md

@@ -1,153 +1,42 @@
-# CLI Jumpstart Plugin
-
-**NOTE:** *This version of the Jumpstart plugin is still under development. The README will be updated continuosly as we refine the plugin.*
-
-The Jumpstart Plugin is a part of the Magnolia CLI's plugin system. This plugin is designed to facilitate the process of starting new projects using predefined templates and bundles. It allows users to choose a template and download associated bundles while performing necessary tasks such as authentication, bundle downloading, extraction, and post-command execution.
+# JumpstartPlugin
+A plugin for [Magnolia CLI](https://docs.magnolia-cms.com/magnolia-cli) to download and set up a new headless or freemarker-based project with Magnolia webapp
 
 ## Installation
-
-The Jumpstart plugin is by default installed in the MGNL plugin-system and ready to be used.
+Within the Magnolia CLI plugin system, this plugin is pre-installed and ready to be used.
 
 ## Usage
-The Jumpstart Plugin enhances the Magnolia CLI by providing a streamlined way to start new projects using predefined templates and bundles. Users can select templates, which are collections of bundles, and have the plugin handle the download, extraction, and execution of post-commands.
-
-**Jumpstart command:**
-
+### Options
+
+| Short          | Long                           | Description                                                                   |
+|----------------|--------------------------------|-------------------------------------------------------------------------------|
+| `-m <version>` | `--magnolia <version>`         | set the Magnolia version; defaults to the latest stable version               |
+| `-s`           | `--snapshot`                   | download the latest snapshot version of the specified or latest stable webapp |
+| `-t <name>`    | `--template <name>`            | choose a template from available project templates                            |
+| `-p <source>`  | `--project-templates <source>` | specify the source to load project templates from                             |
+| `-v`           | `--version`                    | output the version number                                                     |
+| `-h`           | `--help`                       | display help for command                                                      |
+
+### Examples
+#### Jumpstart a project
 ```bash
-magnolia-cli jumpstart
+npx @magnolia/cli jumpstart
 ```
+This command will prompt you with a list of available templates to choose from. Once you select a template, the CLI will download and configure the project with the latest Magnolia version (or with version associated with that template)
 
-This command initiates the **jumpstart** plugin.
-When run, the plugin will prompt the user to select a template. It will then proceed to download and extract the required bundles, executing post-commands if specified, install required plugins, initialize package.json project and create mgnl.config.js.
-
-
-![select-template.png](images/select-template.png)
-
-
-### **command-line options**
-
-You can customize the **jumpstart** plugin's actions using these command-line options:
-- `-t, --template <name>`, choose a template from available project templates
-- `-p, --project-templates-path <path>`, specify the path to load project templates from
-- `-m, --magnolia-version <version>`, set the Magnolia version; defaults to the latest stable version
-- `-s, --snapshot`, download the latest snapshot version of the specified or latest stable webapp
-
-**Template option:**
-
-With this option, you can specify which template to use:
-
+#### Jumpstart a project with specific template
 ```bash
-magnolia-cli jumpstart --template "headless/minimal-headless-spa-demos/dx-core"
+npx @magnolia/cli jumpstart --template "standard-webapps/magnolia-community-webapp"
 ```
+This command will start downloading and configuring project based on "standard-webapps/magnolia-community-webapp" template with latest Magnolia version.
 
-
-**Project templates list:**
-
-The **jumpstart** plugin relies on a list of predefined project templates stored in an external [repository](https://bitbucket.org/magnolia-cms/cli-project-templates/raw/HEAD/projectTemplates.json). 
-You can specify your own project templates list with the *--project-templates-path* command:
-
+#### Jumpstart a project with specific template and specific magnolia version
 ```bash
-magnolia-cli jumpstart -p "<project-templates-path>"
+npx @magnolia/cli jumpstart --template "standard-webapps/magnolia-community-webapp" --magnolia "6.2.11"
 ```
+This command will start downloading and configuring project based on "standard-webapps/magnolia-community-webapp" template with 6.2.11 Magnolia version.
 
+## Plugin Documentation
+For detailed documentation of the plugin, please refer to [Plugin Documentation](https://docs.magnolia-cms.com/magnolia-cli)
 
-## Extensions
-
-The extensions functionality allows for greater flexibility and customizability during the setup process of a new Magnolia project.
-
-### Extension YAML Configuration
-
-The plugin searches for extension YAML files in the following path within your project directory:
-`<rootdir>/extensions/extension.yaml`
-
-This YAML file defines additional prompts and post-command functions, which can be helpful for tailoring the plugin's functionality to specific project requirements.
-
-### Structure of the YAML File
-
-An extension YAML file typically contains the following key sections:
-
-- `extend`: Specifies a JavaScript file that the extension will tie into for additional logic or configuration.
-- `prompts`: A series of input prompts to gather necessary information from the user. Each prompt can specify:
-    - `type`: The type of prompt, such as `input` for user text input.
-    - `name`: The internal name used to reference the collected data.
-    - `message`: The message displayed to the user during the prompt.
-    - `default`: The default value for the prompt, used if the user provides no input.
-- `commands`: Defines actions to be taken after the prompts have been completed, such as:
-    - `post`: Commands to be executed after the setup process. This could involve downloading dependencies, setting up environment variables, etc.
-
-### Example
-
-```yaml
-extend: ./example.js
-prompts:
-  - type: input
-    name: clientId
-    message: Client ID
-    default: clientId_001
-
-  - type: input
-    name: organizationId
-    message: Organization Id
-    default: organizationId_001
-
-  - type: input
-    name: siteId
-    message: Site Id
-    default: siteId_001
-
-commands:
-  post:
-    - function: example
-      retry: 3
-      delay: 1000
-```
-
-### Execution Flow
-
-Upon project initialization, if an extension file is detected, the **Jumpstart** Plugin performs the following steps:
-
-1. **Input Gathering**: It prompts the user for input based on the `prompts` defined within the extension's YAML file.
-
-2. **Configuration Integration**: The plugin retrieves the main **package.json** file. The responses gathered from the prompts are then added to this configuration object under an `answers` property. This augmented **package.json** object is subsequently used to automatically populate the corresponding placeholders within your project files.
-
-3. **Post-Command Execution**: Each `post-command` function specified in the YAML file is executed. These functions have access to the `prompts` object, which contains the user's responses, allowing the functions to perform tasks that are tailored to the user's input.
-
-### Customization Example
-
-After gathering inputs, a file containing placeholders like below:
-```js
-// config.js
-
-export default {
-  clientId: <%=answers.siteId%>,
-  organizationId: <%=answers.organizationId%>,
-  siteId: <%=answers.siteId%>
-};
-```
-will be transformed into:
-```js
-// config.js
-
-export default {
-  clientId: clientId_001,
-  organizationId: organizationId_001,
-  siteId: siteId_001
-};
-```
-
-By using the **Jumpstart** Plugin's extensions functionality, developers can create a more interactive and automated project setup process, making it easier to get started with a new Magnolia project.
-
-## Light-modules folder:
-
-The Jumpstart Plugin initiates a recursive search throughout the project's directory structure for an existing `light-modules` directory. Upon detection, the plugin avoids creating a new one, instead utilizing the existing directory to maintain the pre-configured modules. On the other hand, if a `light-modules` directory is not found, the system will generate one.
-
-**magnolia.properties file:**
-
-The Jumpstart Plugin automatically applies specific modifications to the 'magnolia.properties' files of magnoliaAuthor and magnoliaPublic webapps.
-
-Following properties are modified:
-- 'magnolia.resources.dir' is adjusted to reference the `light-modules` directory.
-- 'magnolia.update.auto' is set to true
-
-## Conclusion
-The Jumpstart Plugin demonstrates an effective way to streamline the process of setting up new projects by providing template-based automation for downloading, extracting, and handling bundles. With its intuitive command-line interface and detailed documentation, users can quickly get started with the Magnolia CLI's powerful plugin system.
+## Magnolia CMS
+This plugin is created to work with Magnolia CMS. For more information, please refer to [Magnolia CMS Documentation](https://docs.magnolia-cms.com/home/)

package/dist/jumpstart-plugin.d.ts

@@ -9,6 +9,7 @@ export declare let i18nInstance: {
 export default class JumpstartPlugin extends PluginTemplate {
     name: string;
     version: any;
+    usage: string;
     projectTemplates?: Array<Template>;
     options: Option[];
     credentials?: Credentials;

package/dist/jumpstart-plugin.js

@@ -33,13 +33,14 @@ export default class JumpstartPlugin extends PluginTemplate {
         super();
         this.name = "jumpstart";
         this.version = pkg.version;
+        this.usage = "[options]";
         i18nInstance = initI18n(this.name);
-        this.description = i18nInstance.t('cmd-option-description');
+        this.description = i18nInstance.t('description');
         this.options = [
-            new Option('-t, --template <name>', i18nInstance.t("cmd-option-template")),
-            new Option('-p, --project-templates-path <path>', i18nInstance.t("cmd-option-project-templates-path")),
-            new Option('-m, --magnolia-version <version>', i18nInstance.t('cmd-option-magnolia-version')),
-            new Option('-s, --snapshot', i18nInstance.t('cmd-option-snapshot'))
+            new Option('-m, --magnolia <version>', i18nInstance.t('option-magnolia-description')),
+            new Option('-s, --snapshot', i18nInstance.t('option-snapshot-description')),
+            new Option('-t, --template <name>', i18nInstance.t("option-template-description")),
+            new Option('-pt, --project-templates <source>', i18nInstance.t("option-projectTemplates-description"))
         ];
     }
     executePostCommands(bundle, file) {
@@ -64,19 +65,13 @@ export default class JumpstartPlugin extends PluginTemplate {
     handleTemplate(template, options) {
         return __awaiter(this, void 0, void 0, function* () {
             if (template.auth) {
-                logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t("prompt-enter-credentials", {
-                    bundle: template.name
-                }));
-                this.credentials = yield askForCredentials();
+                this.credentials = yield askForCredentials(template.name);
             }
             for (const bundle of template.bundles || []) {
                 let file;
                 try {
                     if (bundle.auth === true) {
-                        logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t('prompt-enter-credentials', {
-                            bundle: bundle.name ? bundle.name : bundle.url
-                        }));
-                        const bundleCredentials = yield askForCredentials();
+                        const bundleCredentials = yield askForCredentials(bundle.name ? bundle.name : bundle.url);
                         file = yield downloadBundle(bundle, bundleCredentials, undefined, options);
                     }
                     else {
@@ -87,7 +82,7 @@ export default class JumpstartPlugin extends PluginTemplate {
                     }
                 }
                 catch (e) {
-                    logger.error(e.message);
+                    logger === null || logger === void 0 ? void 0 : logger.error(e.message);
                 }
             }
             yield handleLightModulesFolder();
@@ -110,21 +105,31 @@ export default class JumpstartPlugin extends PluginTemplate {
     setProjectTemplates(options) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
+            let errorMsg;
             try {
-                if ((_a = options.projectTemplatesPath) === null || _a === void 0 ? void 0 : _a.startsWith("http", 0)) {
-                    const res = yield axios.get(options.projectTemplatesPath);
+                if ((_a = options.projectTemplates) === null || _a === void 0 ? void 0 : _a.startsWith("http", 0)) {
+                    errorMsg = i18nInstance.t("error-no-projectTemplates-from-url", { url: options.projectTemplates });
+                    const res = yield axios.get(options.projectTemplates);
                     this.projectTemplates = res.data.projectTemplates;
                 }
-                else if (options.projectTemplatesPath) {
-                    this.projectTemplates = requireFn(path.resolve(options.projectTemplatesPath)).projectTemplates;
+                else if (options.projectTemplates) {
+                    errorMsg = i18nInstance.t("error-no-projectTemplates-from-path", { path: options.projectTemplates });
+                    this.projectTemplates = requireFn(path.resolve(options.projectTemplates)).projectTemplates;
                 }
                 else {
+                    errorMsg = i18nInstance.t("error-no-projectTemplates-from-default");
                     const res = yield axios.get("https://bitbucket.org/magnolia-cms/cli-project-templates/raw/HEAD/projectTemplates.json");
                     this.projectTemplates = res.data.projectTemplates;
                 }
             }
             catch (e) {
-                logger.error(e.message);
+                if (errorMsg) {
+                    throw new Error(errorMsg);
+                }
+                else {
+                    console.error(i18nInstance.t("error-while-getting-projectTemplates"));
+                    throw e;
+                }
             }
         });
     }
@@ -143,7 +148,7 @@ export default class JumpstartPlugin extends PluginTemplate {
                 {
                     type: 'rawlist',
                     name: 'template',
-                    message: 'Please choose a template?',
+                    message: i18nInstance.t('inquirer-prompt-choose-template'),
                     choices: choices
                 }
             ]);
@@ -182,7 +187,7 @@ export default class JumpstartPlugin extends PluginTemplate {
                     return;
                 }
                 else {
-                    logger.info(i18nInstance.t("info-template_not_found", {
+                    logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t("info-template-not-found", {
                         template: options.template
                     }));
                 }
@@ -213,15 +218,13 @@ export default class JumpstartPlugin extends PluginTemplate {
     }
     start(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t("info-jumpstart_started"));
             this.checkFlagsArguments(options);
             yield this.setProjectTemplates(options);
             yield this.chooseTemplate(options);
+            logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t('info-project-downloaded'));
         });
     }
     stop() {
-        return __awaiter(this, void 0, void 0, function* () {
-            logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t("info-jumpstart_stopped"));
-        });
+        return __awaiter(this, void 0, void 0, function* () { });
     }
 }

package/dist/lib/config-helper.js

@@ -14,7 +14,7 @@ const generate = _generate.default;
 const traverse = _traverse.default;
 import beautifyModule from "js-beautify";
 import path from "path";
-import { determinePackageManager, installPackage } from "./helper.js";
+import { determinePackageManager, installCLI } from "./helper.js";
 import ora from "ora";
 import { i18nInstance, logger } from "../jumpstart-plugin.js";
 import _generate from "@babel/generator";
@@ -33,22 +33,35 @@ const BEAUTIFY_OPTIONS = {
 const getLocalConfigPath = () => path.join(process.cwd(), 'mgnl.config.js');
 const getPackageConfigPath = () => path.join(process.cwd(), 'node_modules/@magnolia/cli/mgnl.config.js');
 export const installAdditionalPlugins = (plugins) => __awaiter(void 0, void 0, void 0, function* () {
+    let spinner = ora().start(i18nInstance.t("ora-start-checking-add-plugin"));
+    let showManualInstallMsg = false;
     const pm = determinePackageManager();
-    const addPluginExists = yield execa(pm, 'run mgnl -s -- add-plugin -v'.split(' '), { cwd: process.cwd() });
-    if (addPluginExists.exitCode !== 0 || !addPluginExists.stdout.match(/(\d.)+(\d).*/)) {
-        logger.warn(i18nInstance.t("warn-config-h-no-add-plugin"));
+    try {
+        const addPluginExists = yield execa(pm, 'run mgnl -s -- add-plugin -v'.split(' '), { cwd: process.cwd() });
+        if (addPluginExists.exitCode !== 0 || !addPluginExists.stdout.match(/(\d.)+(\d).*/)) {
+            spinner.warn(i18nInstance.t("ora-warn-no-add-plugin"));
+            showManualInstallMsg = true;
+        }
+        spinner.stop();
+    }
+    catch (e) {
+        showManualInstallMsg = true;
+        spinner.fail(i18nInstance.t("ora-fail-while-add-plugin-check", { errorMsg: e.message }));
+    }
+    if (showManualInstallMsg) {
         let installPluginsText = "";
         plugins.forEach(plugin => {
             installPluginsText = `${installPluginsText} - ${plugin.plugin}\n`;
             if (plugin.pluginArgs) {
-                installPluginsText = `${installPluginsText}${i18nInstance.t("install-plugin-with-args-text", { pluginArgs: JSON5.stringify(plugin.pluginArgs) })}`;
+                installPluginsText = `${installPluginsText}${i18nInstance.t("text-install-plugin-with-args", { pluginArgs: JSON5.stringify(plugin.pluginArgs) })}`;
             }
         });
-        logger.warn(i18nInstance.t("warn-config-h-install-plugins-manually", { installPluginsText: installPluginsText }));
+        logger === null || logger === void 0 ? void 0 : logger.warn(i18nInstance.t("warn-install-plugins-manually", { installPluginsText: installPluginsText }));
         return;
     }
     for (const plugin of plugins) {
         try {
+            let argsMsg;
             const addPluginArgs = `run mgnl -s -- add-plugin ${plugin.plugin}`.split(' ');
             try {
                 if (plugin.pluginArgs !== undefined && plugin.pluginArgs !== 'undefined' && plugin.pluginArgs !== '') {
@@ -56,35 +69,37 @@ export const installAdditionalPlugins = (plugins) => __awaiter(void 0, void 0, v
                 }
             }
             catch (e) {
-                logger.warn(i18nInstance.t('warn-config-h-error-cannot-parse-plugin-args', { pluginArgs: plugin.pluginArgs }));
+                argsMsg = i18nInstance.t('warn-cannot-parse-plugin-args', { pluginArgs: plugin.pluginArgs, plugin: plugin.plugin });
             }
             yield execa(pm, addPluginArgs, {
                 stdio: 'inherit',
                 cwd: process.cwd()
             });
+            if (argsMsg) {
+                logger === null || logger === void 0 ? void 0 : logger.warn(argsMsg);
+            }
+            logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t('info-plugin-installed', { plugin: plugin.plugin }));
         }
         catch (e) {
-            logger.error(i18nInstance.t('error-config-h-while-add-plugin', { plugin: plugin }));
+            logger === null || logger === void 0 ? void 0 : logger.error(i18nInstance.t('error-while-add-plugin', { plugin: plugin.plugin, errorMsg: e.message }));
         }
     }
 });
 export const handleMGNLConfigFile = () => __awaiter(void 0, void 0, void 0, function* () {
     let isMgnlCliInstalled = true;
     if (!fs.existsSync(getPackageConfigPath())) {
-        isMgnlCliInstalled = yield installPackage(determinePackageManager(), "@magnolia/cli@preview");
-        logger === null || logger === void 0 ? void 0 : logger.warn(i18nInstance.t('warn-config-h-could-not-install-cli'));
-    }
-    if (isMgnlCliInstalled && fs.existsSync(getLocalConfigPath())) {
-        handleExistingConfigFile();
-    }
-    else if (isMgnlCliInstalled && !fs.existsSync(getLocalConfigPath())) {
-        createMgnlConfigFile();
+        isMgnlCliInstalled = yield installCLI();
     }
-    else if (!isMgnlCliInstalled && !fs.existsSync(getLocalConfigPath())) {
-        createSimpleMgnlConfigFile();
+    if (isMgnlCliInstalled) {
+        if (fs.existsSync(getLocalConfigPath())) {
+            handleExistingConfigFile();
+        }
+        else {
+            createMgnlConfigFile();
+        }
     }
     else {
-        // the mgnl.config.js exist, do not do anything
+        logger === null || logger === void 0 ? void 0 : logger.error(i18nInstance.t("error-mgnl-cli-not-installed"));
     }
 });
 const handleExistingConfigFile = () => {
@@ -94,8 +109,8 @@ const handleExistingConfigFile = () => {
     const globalLoggerConfig = extractLoggerConfig(packageConfigContent);
     if (!localLoggerConfig && (globalLoggerConfig && globalLoggerConfig[1])) {
         const loggerContent = getLoggerContent(globalLoggerConfig[1]);
-        const newLocalConfigContent = localConfigContent.replace(/(export default \{)/, `$1${loggerContent}`);
-        writeConfigContent(newLocalConfigContent);
+        const newLocalConfigContent = localConfigContent.replace(/(export\s+default\s+\{)/, `$1${loggerContent}`);
+        writeConfigContent(newLocalConfigContent, false);
     }
 };
 function createMgnlConfigFile() {
@@ -111,15 +126,7 @@ function createMgnlConfigFile() {
     plugins: []
     };`;
     const mgnlConfigContent = mgnlConfigPrefix + logger + mgnlConfigSufix;
-    writeConfigContent(mgnlConfigContent);
-}
-function createSimpleMgnlConfigFile() {
-    const mgnlConfigContent = `
-    export default {
-    // Here you can add plugins you want to use with MGNL CLI
-    plugins: []
-    };`;
-    writeConfigContent(mgnlConfigContent);
+    writeConfigContent(mgnlConfigContent, true);
 }
 function getLoggerContent(logger) {
     return `
@@ -131,21 +138,18 @@ const extractLoggerConfig = (content) => {
     const loggerRegex = /(logger\s*:\s*{[^}]*})/s;
     return loggerRegex.exec(content);
 };
-const writeConfigContent = (content) => {
-    const spinner = ora().start(i18nInstance.t("ora-updating-mgnl-config"));
+const writeConfigContent = (content, creating) => {
+    const spinner = ora().start(i18nInstance.t(creating ? "ora-start-creating-config" : "ora-start-updating-config"));
     try {
         fs.writeFileSync(getLocalConfigPath(), js_beautify(content.trim(), BEAUTIFY_OPTIONS), 'utf-8');
+        spinner.succeed(i18nInstance.t(creating ? "ora-succeed-config-created" : "ora-succeed-config-updated"));
     }
     catch (e) {
-        spinner.stop();
-        logger === null || logger === void 0 ? void 0 : logger.error(i18nInstance.t("error-config-h-while-updating-mgnl-config"));
-        console.error(e);
+        spinner.fail(i18nInstance.t(creating ? "ora-fail-creating-config" : "ora-fail-updating-config", { errorMsg: e.message }));
     }
-    spinner.stop();
-    logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t("info-config-h-mgnl-config-updated"));
 };
 export const addConfigProps = (vars) => __awaiter(void 0, void 0, void 0, function* () {
-    const spinner = ora().start(i18nInstance.t("ora-adding-shared-vars"));
+    const spinner = ora().start(i18nInstance.t("ora-start-adding-shared-vars"));
     try {
         const filePath = getLocalConfigPath();
         let content = fs.readFileSync(filePath, 'utf-8');
@@ -198,13 +202,10 @@ export const addConfigProps = (vars) => __awaiter(void 0, void 0, void 0, functi
         if (modificationsMade) {
             const output = generate(ast, {}, content);
             fs.writeFileSync(getLocalConfigPath(), js_beautify(output.code.trim(), BEAUTIFY_OPTIONS), 'utf-8');
-            spinner.stop();
-            logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t("info-config-h-mgnl-vars-added"));
+            spinner.succeed(i18nInstance.t("ora-succeed-shared-vars-added"));
         }
     }
     catch (e) {
-        spinner.stop();
-        logger === null || logger === void 0 ? void 0 : logger.error(i18nInstance.t("error-config-h-while-adding-vars"));
-        console.error(e);
+        spinner.fail(i18nInstance.t("error-while-adding-vars", { errorMsg: e.message }));
     }
 });