@cbs-consulting/generator-btp 1.2.10 → 1.3.0

package/README.md

@@ -1,105 +1,284 @@
-# CAP/UI5 Foundation Generator
+# CBS Best Practice Generator
 
-A Yeoman generator for creating the foundation of CAP/UI5 projects with TypeScript, ESLint, Prettier, and other essential development configurations.
+A modular Yeoman generator for bootstrapping and enhancing SAP CAP and UI5 projects with industry best practices, including TypeScript, linting, formatting, dev containers, and Azure DevOps CI/CD configuration.
 
-## Features
+## Overview
 
-This generator sets up a solid foundation for your CAP/UI5 projects with:
+This generator provides a suite of modular sub-generators that can be used together or independently:
 
-- ✅ **TypeScript** - Full TypeScript configuration with strict settings
-- ✅ **ESLint** - Code quality and linting rules optimized for TypeScript
-- ✅ **Prettier** - Consistent code formatting
-- ✅ **Husky** - Git hooks for pre-commit quality checks
-- ✅ **Jest** - Testing framework with TypeScript support
-- ✅ **GitHub Actions** - CI/CD pipeline for automated testing and building
-- ✅ **VS Code** - Optimized settings and recommended extensions
-- ✅ **Docker** - Container configuration for deployment (optional)
+- 🎯 **Main Entry Point** - Interactive menu to select which generator to run
+- 🚀 **CAP Generator** - Complete CAP project setup with TypeScript, MTA, dev container, and optional Azure DevOps
+- 🎨 **UI5 Generator** - Add best practices to existing UI5 applications (ESLint, UI5lint, TypeScript)
+- 🐳 **Devcontainer Generator** - VS Code dev container for consistent development environments
+- ☁️ **Azure DevOps Setup** - Automated scripts for configuring branch policies, merge strategies, and CI/CD pipelines
+
+## Prerequisites
+
+The **CAP generator** requires [`@sap/cds-dk`](https://www.npmjs.com/package/@sap/cds-dk) to be installed globally, as it invokes `cds init` directly during execution:
+
+```bash
+npm install -g @sap/cds-dk
+```
 
 ## Installation
 
-First, install Yeoman and this generator globally:
+Install Yeoman and this generator globally:
 
 ```bash
-npm install -g yo
-npm install -g @cbs-consulting/generator-btp
+npm install -g yo @cbs-consulting/generator-btp
 ```
 
-Or install locally in your project:
+Or install as a dev dependency:
 
 ```bash
-npm install --save-dev @cbs-consulting/generator-btp
+npm install --save-dev yo @cbs-consulting/generator-btp
+```
+
+## Quick Start
+
+### Interactive Mode (Recommended)
+
+Run the generator and select from the menu:
+
+```bash
+yo @cbs-consulting/btp
+```
+
+### Direct Generator Access
+
+Invoke specific generators directly:
+
+```bash
+# Bootstrap a new CAP project (includes devcontainer + optional Azure DevOps)
+yo @cbs-consulting/btp:cap
+
+# Add best practices to existing UI5 apps
+yo @cbs-consulting/btp:ui5
+
+# Add devcontainer only
+yo @cbs-consulting/btp:devcontainer
+
+# Add Azure DevOps setup scripts only
+yo @cbs-consulting/btp:setup-azure-devops
 ```
 
-## Usage
+## Generators
+
+### 🚀 CAP Generator
+
+**Purpose**: Bootstrap a complete CAP project with all best practices.
+
+> **Requires** `@sap/cds-dk` installed globally (`npm install -g @sap/cds-dk`).
 
-This generator is split into two sub-generators.
+**What it does**:
 
-1. CAP flow
+- Runs `cds init` with TypeScript, MTA, XSUAA, HANA, and sample content
+- Configures ESLint and Prettier (using [@cbs-consulting/tools](https://www.npmjs.com/package/@cbs-consulting/tools))
+- Sets up git workflows with advanced aliases (ticket-based branches, PR automation)
+- Adds pre-commit hooks (linting, formatting) with simple-git-hooks
+- Generates MTA deployment descriptors with environment-specific extensions (dev/test/prod)
+- Configures VS Code with 30+ recommended extensions
+- **Includes devcontainer generator** (always)
+- **Includes setup-azure-devops generator** (optional, if selected)
+
+**Key files added**:
+
+- `.gitignore`, `.gitconfig.aliases`, `.gitattributes`, `.npmrc`
+- `eslint.config.mjs`, `prettier.config.mjs`
+- `mta.yaml` + `mta-ext/{dev,test,prod}.mtaext`
+- `azure-pipelines.yaml` (if Azure DevOps enabled)
+- `.devcontainer/` folder
+- `scripts/setup-azure-devops/` folder (if Azure DevOps enabled)
+
+**Usage**:
 
 ```bash
-mkdir my-cap
-cd my-cap
+mkdir my-cap-project
+cd my-cap-project
 yo @cbs-consulting/btp:cap
-# read and execute the printed steps shown in the terminal
 ```
 
-2. UI5 flow
+---
+
+### 🎨 UI5 Generator
+
+**Purpose**: Add best practices to existing UI5 applications.
+
+**What it does**:
+
+- Auto-detects UI5 apps in the `app/` folder (by finding `ui5.yaml`)
+- Adds ESLint and UI5lint configurations per app
+- Configures TypeScript to work with CAP-generated models
+- Adds npm scripts for linting and UI5-specific linting
+
+**Key files added** (per app):
+
+- `eslint.config.mjs`, `ui5lint.config.mjs`
+- Updates `package.json` and `tsconfig.json`
+
+**Usage**:
 
 ```bash
-mkdir my-ui5
-cd my-ui5
-# ensure you have a UI5 project skeleton (or after cds init)
+# Run from CAP project root with app/ folder
 yo @cbs-consulting/btp:ui5
-# read and execute the printed steps in the terminal
 ```
 
-The CAP sub-generator copies all templates from generators/app/templatesCAP into your project and merges additions from generators/app/additionsCAP into existing files. The scripting.txt is shown but not executed automatically.
+---
+
+### 🐳 Devcontainer Generator
+
+**Purpose**: Set up VS Code dev container for consistent development environments.
+
+**What it does**:
+
+- Creates `.devcontainer/` configuration using CBS Docker image
+- Pre-configures 30+ VS Code extensions
+- Auto-installs Cloud Foundry and Azure DevOps CLI tools on container creation
+- Provides isolated, reproducible development environment
+
+**Key files added**:
+
+- `.devcontainer/devcontainer.json`
+- `.devcontainer/Dockerfile`
+- `.devcontainer/post-create.sh`
+
+**Usage**:
+
+```bash
+yo @cbs-consulting/btp:devcontainer
+```
+
+**Note**: This generator is automatically included when using the CAP generator.
+
+---
+
+### ☁️ Azure DevOps Setup Generator
+
+**Purpose**: Create automation scripts for Azure DevOps branch policies and CI/CD pipelines.
 
-## Generated Project Structure
+**What it does**:
 
+- Generates bash script to automate Azure DevOps configuration
+- Creates `main` and `development` branches with policies
+- Configures code review requirements, merge strategies, and build validation
+- Sets up Azure Pipeline from `azure-pipelines.yaml`
+
+**Key files added**:
+
+- `scripts/setup-azure-devops/setup.sh` (automation script)
+- `scripts/setup-azure-devops/azure-devops.env` (configuration variables)
+- `scripts/setup-azure-devops/README.md` (detailed documentation)
+
+**Usage**:
+
+```bash
+yo @cbs-consulting/btp:setup-azure-devops
+# Then run: bash scripts/setup-azure-devops/setup.sh
 ```
-my-project/
-├── src/                     # Source TypeScript files
-├── tests/                   # Test files (if Jest is selected)
-├── dist/                    # Compiled output (after build)
-├── .github/workflows/       # GitHub Actions CI/CD (if selected)
-├── .vscode/                 # VS Code settings (if selected)
-├── .eslintrc.js            # ESLint configuration
-├── .prettierrc             # Prettier configuration
-├── .gitignore              # Git ignore rules
-├── tsconfig.json           # TypeScript configuration
-├── jest.config.js          # Jest configuration (if selected)
-├── package.json            # Project dependencies and scripts
-└── README.md               # Project documentation
+
+**Note**: This generator is automatically included when using the CAP generator with Azure DevOps enabled.
+
+---
+
+## Generated Project Structure (CAP)
+
+When using the CAP generator, your project will include:
+
+``` tree
+my-cap-project/
+├── .devcontainer/              # Dev container configuration
+│   ├── devcontainer.json
+│   ├── Dockerfile
+│   └── post-create.sh
+├── .vscode/                    # VS Code settings & extensions
+│   ├── settings.json
+│   └── extensions.json
+├── app/                        # UI5 applications (from cds init)
+├── db/                         # Database models (from cds init)
+├── srv/                        # Service definitions (from cds init)
+├── mta-ext/                    # MTA extensions for environments
+│   ├── dev.mtaext
+│   ├── test.mtaext
+│   └── prod.mtaext
+├── scripts/                    # Automation scripts
+│   └── setup-azure-devops/     # Azure DevOps setup (if enabled)
+│       ├── setup.sh
+│       ├── azure-devops.env
+│       └── README.md
+├── .gitignore                  # Comprehensive ignore patterns
+├── .gitconfig.aliases          # Git workflow aliases
+├── .gitattributes              # Line ending configuration
+├── .npmrc                      # npm settings
+├── azure-pipelines.yaml        # CI/CD pipeline (if enabled)
+├── tsconfig.json               # Project TypeScript config
+├── eslint.config.mjs           # ESLint configuration
+├── prettier.config.mjs         # Prettier configuration
+├── mta.yaml                    # MTA deployment descriptor
+└── package.json                # Dependencies and scripts
 ```
 
 ## Available Scripts
 
-The generated project includes these npm scripts:
+The CAP generator adds these npm scripts:
+
+**Code Quality**:
 
-- `npm run build` - Compile TypeScript to JavaScript
-- `npm run build:watch` - Watch mode compilation
-- `npm run lint` - Run ESLint on your code
-- `npm run lint:fix` - Fix auto-fixable ESLint issues
 - `npm run format` - Format code with Prettier
 - `npm run format:check` - Check if code is properly formatted
-- `npm test` - Run Jest tests (if enabled)
-- `npm run test:watch` - Run tests in watch mode
-- `npm run test:coverage` - Generate test coverage report
+- `npm run lint` - Run ESLint
+- `npm run lint:fix` - Fix auto-fixable ESLint issues
+
+**Testing & Building**:
+
+- `npm test` - Run tests
+- `npm run build` - Build TypeScript
+- `npm run coverage-report` - Generate test coverage report
+
+**Deployment**:
+
+- `npm run build:mta` - Build MTA archive
+- `npm run deploy-dev` - Deploy to dev environment
+
+**Utilities**:
+
+- `npm run git-config` - Set up git aliases
+- `npm run check-deps` - Check for outdated dependencies
+- `npm run upgrade-deps` - Upgrade dependencies (minor versions)
+
+**Git Hooks**:
+
+- Pre-commit hook automatically runs linting and formatting on staged files
+
+## Key Features
+
+- ✅ **TypeScript-first** with strict compiler settings
+- ✅ **Code quality** enforced via ESLint, Prettier, and pre-commit hooks
+- ✅ **Git workflows** with advanced aliases for ticket-based development
+- ✅ **MTA deployment** with environment-specific configurations
+- ✅ **Dev containers** for reproducible development environments
+- ✅ **Azure DevOps** automation for branch policies and CI/CD
+- ✅ **VS Code optimized** with 30+ recommended extensions
+- ✅ **UI5 linting** with @ui5/linter integration
+- ✅ **Centralized configs** via @cbs-consulting/tools package
 
 ## Development
 
 To develop this generator locally:
 
-1. Clone this repository
-2. Install dependencies: `npm install`
-3. Link the generator: `npm link`
-4. Test in a new directory: `yo @cbs-consulting/btp`
+```bash
+git clone <repository-url>
+cd generator-btp
+npm install
+npm link
+yo @cbs-consulting/btp
+```
+
+Run tests:
 
-## Contributing
+```bash
+npm test
+npm run test:watch
+npm run test:coverage
+```
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
+See [DEVELOPMENT.md](DEVELOPMENT.md) for more details.

package/generators/app/__tests__/index.test.js

@@ -19,6 +19,25 @@ describe("generator-btp:app", () => {
         .run(join(__dirname, "../index.js"))
         .withPrompts({
           kind: "cap",
+          // CAP generator prompts
+          projectName: "Test Project",
+          customerName: "Test Customer",
+          dbSchema: "TEST_SCHEMA",
+          useAzureDevOps: true,
+          azureRepoUrl:
+            "https://dev.azure.com/testorg/testproject/_git/test-repo",
+          useBestPractices: true,
+          cdsFeatures: [
+            "typescript",
+            "mta",
+            "xsuaa",
+            "hana",
+            "sqlite",
+            "html5-repo",
+            "tiny-sample",
+            "http",
+            "test",
+          ],
         })
         .withOptions({
           skipInstall: true,
@@ -98,18 +117,86 @@ describe("generator-btp:app", () => {
     });
   });
 
+  // ========================================
+  // Generator: setup-azure-devops
+  // ========================================
+  describe("when user selects setup-azure-devops", () => {
+    let runResult;
+
+    // Run the generator with setup-azure-devops selection
+    beforeAll(async () => {
+      runResult = await helpers
+        .run(join(__dirname, "../index.js"))
+        .withPrompts({
+          kind: "setup-azure-devops",
+          projectName: "Test Project",
+          azureRepoUrl:
+            "https://dev.azure.com/testorg/testproject/_git/test-repo",
+          useBestPractices: true,
+        });
+    });
+
+    // Restore the environment after tests
+    afterAll(() => {
+      if (runResult) {
+        runResult.restore();
+      }
+    });
+
+    // Test that the correct generator is composed based on user selection
+    it("should compose with setup-azure-devops generator", () => {
+      expect(runResult.generator.kind).toBe("setup-azure-devops");
+    });
+  });
+
   // ========================================
   // Test all prompt choices
   // ========================================
   describe("prompting", () => {
-    it.each(["cap", "ui5", "devcontainer"])(
+    it.each(["cap", "ui5", "devcontainer", "setup-azure-devops"])(
       "should accept '%s' as valid choice",
       async (choice) => {
+        const prompts = {
+          kind: choice,
+        };
+
+        // Add CAP-specific prompts
+        if (choice === "cap") {
+          Object.assign(prompts, {
+            projectName: "Test Project",
+            customerName: "Test Customer",
+            dbSchema: "TEST_SCHEMA",
+            useAzureDevOps: true,
+            azureRepoUrl:
+              "https://dev.azure.com/testorg/testproject/_git/test-repo",
+            useBestPractices: true,
+            cdsFeatures: [
+              "typescript",
+              "mta",
+              "xsuaa",
+              "hana",
+              "sqlite",
+              "html5-repo",
+              "tiny-sample",
+              "http",
+              "test",
+            ],
+          });
+        }
+
+        // Add setup-azure-devops-specific prompts
+        if (choice === "setup-azure-devops") {
+          Object.assign(prompts, {
+            projectName: "Test Project",
+            azureRepoUrl:
+              "https://dev.azure.com/testorg/testproject/_git/test-repo",
+            useBestPractices: true,
+          });
+        }
+
         const runResult = await helpers
           .run(join(__dirname, "../index.js"))
-          .withPrompts({
-            kind: choice,
-          })
+          .withPrompts(prompts)
           .withOptions({
             skipInstall: true,
           })

package/generators/app/index.js

@@ -33,6 +33,10 @@ export default class extends Generator {
             name: "Add devcontainer configuration",
             value: "devcontainer",
           },
+          {
+            name: "Setup Azure DevOps configuration",
+            value: "setup-azure-devops",
+          },
         ],
       },
     ]);
@@ -60,6 +64,13 @@ export default class extends Generator {
         Generator: DevcontainerGenerator,
         path: resolve(__dirname, "../devcontainer"),
       });
+    } else if (this.kind === "setup-azure-devops") {
+      const { default: SetupAzureDevOpsGenerator } =
+        await import("../setup-azure-devops/index.js");
+      this.composeWith({
+        Generator: SetupAzureDevOpsGenerator,
+        path: resolve(__dirname, "../setup-azure-devops"),
+      });
     } else {
       this.log(chalk.red("Unknown selection"));
     }