@magnolia/cli-jumpstart-plugin 1.0.0-preview.3 → 1.0.0-preview.5

package/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2024 Magnolia International Ltd.
+(http://www.magnolia-cms.com). All rights reserved.
+
+
+The software is dual-licensed under both the Magnolia
+Network Agreement and the GNU General Public License.
+You may elect to use one or the other of these licenses.
+
+The software is distributed in the hope that it will be
+useful, but AS-IS and WITHOUT ANY WARRANTY; without even the
+implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, or NONINFRINGEMENT.
+Redistribution, except as permitted by whichever of the GPL
+or MNA you select, is prohibited.
+
+1. For the GPL license (GPL), you can redistribute and/or
+modify this file under the terms of the GNU General
+Public License, Version 3, as published by the Free Software
+Foundation.  You should have received a copy of the GNU
+General Public License, Version 3 along with this program;
+if not, write to the Free Software Foundation, Inc., 51
+Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+2. For the Magnolia Network Agreement (MNA), this file
+and the accompanying materials are made available under the
+terms of the MNA which accompanies this distribution, and
+is available at http://www.magnolia-cms.com/mna.html

package/README.md

@@ -27,14 +27,17 @@ When run, the plugin will prompt the user to select a template. It will then pro
 ### **command-line options**
 
 You can customize the **jumpstart** plugin's actions using these command-line options:
-- `-t, --template <name>`:  Choose template.
-- `-p, --projectTemplatesPath <path>`: Specify from where the projectTemplates should be loaded.
+- `-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:
 
 ```bash
-magnolia-cli jumpstart --template "headless/minimal-headless-spa-demos/dx-core/latest"
+magnolia-cli jumpstart --template "headless/minimal-headless-spa-demos/dx-core"
 ```
 
 
@@ -47,7 +50,94 @@ You can specify your own project templates list with the *--project-templates-pa
 magnolia-cli jumpstart -p "<project-templates-path>"
 ```
 
-**Light-modules folder:**
+
+## 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.
 

package/dist/jumpstart-plugin.d.ts

@@ -1,23 +1,26 @@
 import { PluginTemplate } from '@magnolia/cli-plugin-template';
 import { Option } from 'commander';
-import { PluginOptions, Template, Bundle, TemplateWithoutChildren } from "./types/types.js";
+import { PluginOptions, Template, Bundle, TemplateWithoutChildren, Credentials } from "./types/types.js";
 import { Logger } from "winston";
 export declare let logger: Logger;
+export declare let i18nInstance: {
+    t(key: string, options?: any): string;
+};
 export default class JumpstartPlugin extends PluginTemplate {
     name: string;
     version: any;
-    description: any;
     projectTemplates?: Array<Template>;
     options: Option[];
+    credentials?: Credentials;
+    description: string;
     constructor();
     executePostCommands(bundle: Bundle, file: string): Promise<void>;
-    handleTemplate(template: TemplateWithoutChildren): Promise<void>;
+    handleTemplate(template: TemplateWithoutChildren, options: PluginOptions): Promise<void>;
     setProjectTemplates(options: PluginOptions): Promise<void>;
-    promptTemplateSelection(templates: Array<Template>): Promise<TemplateWithoutChildren | undefined>;
+    promptTemplateSelection(templates: Array<Template>, names?: string[]): Promise<TemplateWithoutChildren | undefined>;
     findTemplateByIdentifier(identifier: string): TemplateWithoutChildren | undefined;
     chooseTemplate(options: PluginOptions): Promise<void>;
     init(winstonLogger: Logger): Promise<void>;
     start(options: PluginOptions): Promise<void>;
     stop(): Promise<void>;
-    help(): Promise<void>;
 }

package/dist/jumpstart-plugin.js

@@ -19,17 +19,27 @@ import { downloadBundle } from "./lib/download.js";
 import { PostCommands } from "./types/types.js";
 import { installDependencies } from "./lib/install.js";
 import path from "path";
-import { handleLightModulesFolder, initializeNodeProject, installAdditionalPlugins } from "./lib/helper.js";
+import { askForCredentials, handleLightModulesFolder, initI18n, initializeNodeProject } from "./lib/helper.js";
+import { compileCustomPrompts, evaluateCustomPrompts } from "./lib/extensions.js";
+import { addConfigProps } from "./lib/config-helper.js";
+import { installAdditionalPlugins } from "./lib/config-helper.js";
+const extensionsPath = path.resolve("./extensions/extension.yaml");
 export let logger;
+export let i18nInstance = {
+    t(key, options) { return key; }
+};
 export default class JumpstartPlugin extends PluginTemplate {
     constructor() {
         super();
         this.name = "jumpstart";
         this.version = pkg.version;
-        this.description = pkg.description;
+        i18nInstance = initI18n(this.name);
+        this.description = i18nInstance.t('cmd-option-description');
         this.options = [
-            new Option('-t, --template <name>', 'Choose template'),
-            new Option('-p, --project-templates-path <path>', 'Specify from where the projectTemplates should be loaded')
+            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'))
         ];
     }
     executePostCommands(bundle, file) {
@@ -40,6 +50,7 @@ export default class JumpstartPlugin extends PluginTemplate {
                 switch (command) {
                     case PostCommands.Extract:
                     case PostCommands.ExtractAndOverride:
+                    case PostCommands.ExtractAndUnfold:
                         yield extract(bundle, file, command);
                         break;
                     case PostCommands.NpmInstall:
@@ -50,51 +61,26 @@ export default class JumpstartPlugin extends PluginTemplate {
             }
         });
     }
-    handleTemplate(template) {
+    handleTemplate(template, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            let templateCredentials;
             if (template.auth) {
-                console.log("Please enter credentials for ", template.name);
-                templateCredentials = yield inquirer
-                    .prompt([
-                    {
-                        type: 'input',
-                        name: 'username',
-                        message: 'Username'
-                    },
-                    {
-                        type: 'password',
-                        name: 'password',
-                        message: 'Password'
-                    }
-                ]);
+                logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t("prompt-enter-credentials", {
+                    bundle: template.name
+                }));
+                this.credentials = yield askForCredentials();
             }
             for (const bundle of template.bundles || []) {
-                let credentials = null;
                 let file;
                 try {
-                    if (bundle.auth === "inherit") {
-                        file = yield downloadBundle(bundle, templateCredentials, undefined);
-                    }
-                    else if (bundle.auth) {
-                        console.log("Please enter credentials for ", bundle.name ? bundle.name : bundle.url);
-                        credentials = yield inquirer
-                            .prompt([
-                            {
-                                type: 'input',
-                                name: 'username',
-                                message: 'Username'
-                            },
-                            {
-                                type: 'password',
-                                name: 'password',
-                                message: 'Password'
-                            }
-                        ]);
-                        file = yield downloadBundle(bundle, credentials, undefined);
+                    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();
+                        file = yield downloadBundle(bundle, bundleCredentials, undefined, options);
                     }
                     else {
-                        file = yield downloadBundle(bundle, null, undefined);
+                        file = yield downloadBundle(bundle, this.credentials, undefined, options);
                     }
                     if (file) {
                         yield this.executePostCommands(bundle, file);
@@ -109,21 +95,31 @@ export default class JumpstartPlugin extends PluginTemplate {
             if (template.plugins) {
                 yield installAdditionalPlugins(template.plugins);
             }
+            if (template.configVars) {
+                yield addConfigProps(template.configVars);
+            }
+            const extensions = yield evaluateCustomPrompts(extensionsPath);
+            if (extensions === null || extensions === void 0 ? void 0 : extensions.answers) {
+                yield compileCustomPrompts(extensions === null || extensions === void 0 ? void 0 : extensions.answers);
+            }
+            if (extensions === null || extensions === void 0 ? void 0 : extensions.executePostCommands) {
+                yield extensions.executePostCommands(extensions === null || extensions === void 0 ? void 0 : extensions.answers);
+            }
         });
     }
     setProjectTemplates(options) {
-        var _a;
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             try {
                 if ((_a = options.projectTemplatesPath) === null || _a === void 0 ? void 0 : _a.startsWith("http", 0)) {
                     const res = yield axios.get(options.projectTemplatesPath);
                     this.projectTemplates = res.data.projectTemplates;
                 }
                 else if (options.projectTemplatesPath) {
-                    this.projectTemplates = requireFn(path.join(process.cwd(), options.projectTemplatesPath)).projectTemplates;
+                    this.projectTemplates = requireFn(path.resolve(options.projectTemplatesPath)).projectTemplates;
                 }
                 else {
-                    const res = yield axios.get("https://git.magnolia-cms.com/rest/api/latest/projects/SERVICES/repos/cli-project-templates/raw/projectTemplates.json");
+                    const res = yield axios.get("https://bitbucket.org/magnolia-cms/project-templates/raw/HEAD/projectTemplates.json");
                     this.projectTemplates = res.data.projectTemplates;
                 }
             }
@@ -132,8 +128,8 @@ export default class JumpstartPlugin extends PluginTemplate {
             }
         });
     }
-    promptTemplateSelection(templates) {
-        return __awaiter(this, void 0, void 0, function* () {
+    promptTemplateSelection(templates_1) {
+        return __awaiter(this, arguments, void 0, function* (templates, names = []) {
             if (!templates || !templates.length) {
                 return;
             }
@@ -151,11 +147,14 @@ export default class JumpstartPlugin extends PluginTemplate {
                     choices: choices
                 }
             ]);
+            if (template.name) {
+                names.push(template.name);
+            }
             if (template.children && template.children.length) {
-                return this.promptTemplateSelection(template.children);
+                return this.promptTemplateSelection(template.children, names);
             }
             if (template.bundles || template.plugins) {
-                return template;
+                return Object.assign(Object.assign({}, template), { name: names.join("/") });
             }
         });
     }
@@ -179,16 +178,18 @@ export default class JumpstartPlugin extends PluginTemplate {
             if (typeof options.template === 'string') {
                 const template = this.findTemplateByIdentifier(options.template);
                 if (template) {
-                    yield this.handleTemplate(template);
+                    yield this.handleTemplate(template, options);
                     return;
                 }
                 else {
-                    logger.info(`The '${options.template}' template was not found.`);
+                    logger.info(i18nInstance.t("info-template_not_found", {
+                        template: options.template
+                    }));
                 }
             }
             const template = yield this.promptTemplateSelection(this.projectTemplates);
             if (template) {
-                yield this.handleTemplate(template);
+                yield this.handleTemplate(template, options);
             }
         });
     }
@@ -199,19 +200,14 @@ 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(`'JumpstartPlugin' plugin started succesfully.`);
+            logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t("info-jumpstart_started"));
             yield this.setProjectTemplates(options);
             yield this.chooseTemplate(options);
         });
     }
     stop() {
         return __awaiter(this, void 0, void 0, function* () {
-            console.log("Plugin stopped");
-        });
-    }
-    help() {
-        return __awaiter(this, void 0, void 0, function* () {
-            console.log("Plugin help");
+            logger === null || logger === void 0 ? void 0 : logger.info(i18nInstance.t("info-jumpstart_stopped"));
         });
     }
 }

package/dist/lib/config-helper.d.ts

@@ -1,3 +1,4 @@
-import { PluginRequirement } from "../types/types.js";
+import { PluginRequirement } from "../types/types";
+export declare const installAdditionalPlugins: (plugins: Array<PluginRequirement>) => Promise<void>;
 export declare const handleMGNLConfigFile: () => Promise<void>;
-export declare const installAndConfigPlugins: (plugins: Array<PluginRequirement>) => Promise<void>;
+export declare const addConfigProps: (vars: any) => Promise<void>;