@appxdigital/appx-core-cli 1.0.0

package/README.md

@@ -0,0 +1,159 @@
+<p align="center">
+  <a href="https://appx-digital.com/" target="_blank">
+    <img src="./assets/logo_appx.svg" width="300" alt="Appx Logo" />
+  </a>
+</p>
+
+## Description
+
+<p style="text-align: left;">
+This project is a foundational Node.js boilerplate built with  <a href="https://nestjs.com/" target="_blank">NestJS</a>, <a href="https://www.prisma.io/" target="_blank">Prisma ORM</a>, and <a href="https://graphql.org/" target="_blank">GraphQL</a>. It simplifies the development process by using Prisma ORM as the single source of truth, automatically generating and managing all essential components of your application.
+</p>
+
+## Installation
+
+1. Open your terminal and run the following command:
+   ```bash
+   npm install appx-core-cli -g
+   appx-core create
+   ```
+2. Follow the prompts provided by the setup wizard. This will scaffold a new NestJS project with `appx-core` pre-integrated.
+3. Open created project in your favorite IDE.
+
+## Configure Database Schema
+
+1. Open the `prisma/schema.prisma` file.
+2. Modify this file to define your application's specific data models. You can add new models, fields, and relations as needed.
+
+Note: If you already have a database created and want to import the structure, use the following command:
+
+```
+npx prisma db pull
+```
+
+**This command will override the schema.prisma file, please ensure that the original configurations and models are kept (you can adapt User and Session model, but it's advised to keep all default attributes)**
+
+## Generate Modules and Prisma Client
+
+1. After editing your schema, generate the modules for each model by running:
+   ```bash
+   appx-core generate
+   ```
+2. This command also updates the `@prisma/client` library within your `node_modules` to match your defined schema, providing type-safe database access. This command should be run everytime you make a change to your prisma schema.
+
+## Apply Database Migrations
+
+1. To create the necessary database tables and apply your schema changes, run:
+   ```bash
+   npx prisma migrate dev
+   ```
+2. This will:
+    * Create a new SQL migration file reflecting the changes between your current schema and the last migration.
+    * Apply the migration to your database.
+
+## Run the Application
+
+1. Start your application in development mode using:
+   ```bash
+   npm run start:dev
+   ```
+2. The application will start on `http://localhost:3000` or the port specified during your setup, you can change this in the `.env` file.
+
+## Register Your First User
+
+1. To create a user account, send an HTTP `POST` request to the `/auth/register` endpoint.
+2. The request body must be JSON and include the `email` and `password`:
+   ```json
+   {
+     "email": "email@example.com",
+     "password": "password"
+   }
+   ```
+3. On success, you'll receive a JSON response confirming registration and containing the new user's details.
+
+## Log In
+
+1. To log in with the registered user, send an HTTP `POST` request to the `/auth/login` endpoint.
+2. The request body must be JSON and include the same fields used for registration:
+   ```json
+   {
+     "email": "email@example.com",
+     "password": "password"
+   }
+   ```
+3. On success, you'll receive a JSON response confirming login and containing the user's details.
+
+## Permissions
+
+This project uses RBAC to control user access. Permissions are defined in a configuration file and checked automatically before controller actions and during database queries.
+
+### Configuration
+
+* Permissions are defined in the `src/config/permissions.config.ts` file.
+* The configuration structure is hierarchical: `ModelName` -> `RoleName` -> `ActionName` -> `Rule`.
+
+    ```typescript
+    export const PermissionsConfig: PermissionsConfigType = {
+      ModelName: { // e.g., 'User'; links to controller's entityName
+        RoleName: { // e.g., 'ADMIN', 'CLIENT'; matches user roles
+          ActionName: Rule, // e.g., 'findUnique', 'update'
+          // ... other actions for this role/model
+        },
+         // ... other roles for this model
+      },
+      // ... other models
+    };
+    ```
+
+### Permission Rules & Effects
+
+The `Rule` assigned to an action determines if a user with that role can perform the action:
+
+* **`'ALL'`:** Grants unrestricted access for the specific action.
+* **Object `{ conditions: { ... } }`:** Grants access *only if* the specified conditions match the data being accessed.
+    * These `conditions` (e.g., `{ id: '$USER_ID' }`) are automatically added as `WHERE` clauses to the underlying database query by the `PrismaService`.
+    * Placeholders like `$USER_ID` are replaced with the current user's actual data (e.g., `req.user.id`).
+* **Missing Rule:** If no rule (`'ALL'` or an object) is defined for an action under the user's role, access is **denied**.
+
+### Applying Permissions
+
+* Protect controller methods by decorating them with `@Permission('actionName')`. This links the method to an `ActionName` in your `permissions.config.ts`.
+    * Methods *without* the `@Permission` decorator are not subject to specific action checks by the `RbacGuard` and are allowed access.
+
+        ```typescript
+        @Controller('users')
+        export class UserController extends CoreController<User>  {  
+  
+          @Get(':id')
+          @Permission('findUnique') // Checks config for User -> Role -> findUnique
+          async findOne(@Param('id') id: string) {
+            /* ... */
+          }
+  
+          @Get('/public/info')
+          // No @Permission decorator - RbacGuard allows by default access for this route
+          async getPublicInfo() { 
+            /* ... */ 
+          }
+        
+           static get entityName(): string {
+            return 'User';
+          }
+        }
+        ```
+
+### Adding Permissions for a New Action
+
+1. **Decorate Method & Choose Name:** Add the `@Permission('yourActionName')` decorator to the relevant controller method, choosing a unique string for `'yourActionName'` (e.g., `'publishItem'`, `'resetPassword'`).
+
+2. **Update Config:** Edit `permissions.config.ts`. Add the `actionName` under the appropriate `ModelName` -> `RoleName`(s). Set the rule:
+    * Use `'ALL'` for full access.
+    * Use an object like `{ conditions: { field: '$USER_ID' } }` for conditional access (enforced by the database query).
+
+    ```typescript
+    // Example: Adding 'publishItem' rule to Article model config
+      Article: {
+        ADMIN: { /*...,*/ publishItem: 'ALL' },
+        EDITOR: { /*...,*/ publishItem: { conditions: { authorId: '$USER_ID' } } },
+      },
+    ```

package/package.json

@@ -0,0 +1,26 @@
+{
+    "type": "module",
+    "name": "@appxdigital/appx-core-cli",
+    "version": "1.0.0",
+    "main": "index.js",
+    "scripts": {
+        "npm:publish": "npm publish --access public",
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [],
+    "author": "",
+    "license": "ISC",
+    "bin": {
+        "appx-core": "./wizard.js"
+    },
+    "dependencies": {
+        "@inquirer/prompts": "^7.0.0",
+        "@nestjs/cli": "^11.0.6",
+        "cli-progress": "^3.12.0",
+        "commander": "^12.1.0",
+        "fs-extra": "^11.2.0",
+        "handlebars": "^4.7.8",
+        "inquirer": "^12.0.0"
+    },
+    "description": ""
+}

package/templates/adminjs/admin.template.js

@@ -0,0 +1,143 @@
+import { DynamicModule } from '@nestjs/common';
+import { addBasicFilters, createActions, createPermissionHandler, dynamicImport, getAdminJSResources } from './utils';
+import { initializeComponents } from './component-loader';
+import { readFileSync } from 'fs';
+import { getDMMF } from '@prisma/sdk';
+import { PrismaService } from '@appxdigital/appx-core';
+import { PrismaModule } from "../prisma/prisma.module";
+
+const DEFAULT_ADMIN = {
+    email: 'joao.duvido@appx.pt',
+    password: 'password',
+};
+
+const authenticate = async (email: string, password: string) => {
+    if (email === DEFAULT_ADMIN.email && password === DEFAULT_ADMIN.password) {
+        return Promise.resolve(DEFAULT_ADMIN);
+    }
+    return null;
+};
+
+export async function createAdminJsModule(): Promise<DynamicModule> {
+    // Due to AdminJS only allowing ESM now, we need to use dynamic imports to load the modules, this function can be found within src/backoffice/utils.ts
+    const { default: AdminJS } = await dynamicImport('adminjs');
+    const { Database, Resource } = await dynamicImport('@adminjs/prisma');
+    const { AdminModule } = await dynamicImport('@adminjs/nestjs');
+    const { default: importExportFeature } = await dynamicImport('@adminjs/import-export');
+    const { default: passwordFeature } = await dynamicImport('@adminjs/passwords');
+    const argon2 = await dynamicImport('argon2');
+
+    // Below, this function in src/backoffice/utils.ts is used to get the resources you want to expose to AdminJS
+    const resources = getAdminJSResources();
+
+    // Once you create customized components, you can load them on the componentLoader just like the Dashboard component example
+
+    const { componentLoader, Components } = await initializeComponents();
+
+    // This gets the models from the Prisma schema, and then creates the AdminJS resources
+    const schemaPath = './prisma/schema.prisma';
+    const schema = readFileSync(schemaPath, 'utf-8');
+    const dmmf = await getDMMF({ datamodel: schema });
+
+    const models = [];
+
+    for (const resource of resources) {
+        const model = dmmf.datamodel.models.find(
+            (model) => model.name === resource.name,
+        );
+
+        models.push({
+            model,
+            options: resource.options,
+            features: model.name === 'User' ? [
+                passwordFeature({
+                    properties: {
+                        encryptedPassword: 'password',
+                        password: 'plainPassword',
+                    },
+                    hash: argon2.hash,
+                    componentLoader,
+                }),
+            ] : [],
+        });
+    }
+
+    AdminJS.registerAdapter({ Database, Resource });
+
+
+    return AdminModule.createAdminAsync({
+        imports: [PrismaModule],
+        inject: [PrismaService],
+        useFactory: async (prisma: PrismaService) => {
+
+            // If you comment out this function below, you will be able to access the AdminJS with the DEFAULT_ADMIN credentials at the top of this file
+            // With that, you can create a new user, and then undo the comment on this function to disable the default admin, using the new user you created
+            const authenticate = async (email: string, password: string) => {
+                const user = await prisma.user.findUnique({
+                    where: {
+                        email
+                    }
+                });
+
+                if (!user || user.role !== 'ADMIN') {
+                    return null;
+                }
+
+                const isPasswordValid = await argon2.verify(user.password, password);
+
+                return isPasswordValid ? Promise.resolve({ email: user.email, role: user.role, id: user.id }) : null;
+            }
+
+            return {
+                adminJsOptions: {
+                    rootPath: '/admin',
+                    // As you can see below, you can customize the dashboard component, which is the first page you see when you access the AdminJS
+                    dashboard: {
+                        component: Components.Dashboard,
+                        handler: async () => {
+                            return { some: 'output' };
+                        },
+                    },
+                    branding: {
+                        // Here you can change the company name, which appears on the browser's tab
+                        companyName: 'AppX Core Wizard',
+                        // This removes the "Made with love (...)" from the footer
+                        withMadeWithLove: false,
+                        // Here you can change the logo, currently using AppX's as an example
+                        logo: 'https://i.ibb.co/XZNRS5m/appxdigitalcom-logo.jpg',
+                    },
+                    resources: models.map((m) => {
+                        return {
+                            resource: { model: m.model, client: prisma },
+                            options: {
+                                ...m.options,
+                                actions: createActions(),
+                            },
+                            features: [...(m.features || []), importExportFeature({
+                                componentLoader
+                            })],
+                        };
+                    }),
+
+                    componentLoader,
+                },
+                auth: {
+                    authenticate,
+                    cookieName: process.env.SESSION_COOKIE_NAME,
+                    cookiePassword: process.env.SESSION_SECRET,
+                },
+                sessionOptions: {
+                    resave: false,
+                    saveUninitialized: true,
+                    secret: process.env.SESSION_SECRET,
+                    cookie: {
+                        httpOnly: process.env.NODE_ENV === 'production',
+                        //secure: process.env.NODE_ENV === 'production',
+                        secure: false,
+                    },
+                    name: process.env.SESSION_COOKIE_NAME,
+                },
+            };
+        },
+    });
+}

package/templates/adminjs/adminjs-app.module.template.js

@@ -0,0 +1,48 @@
+import {
+    MiddlewareConsumer,
+    Module,
+    NestModule,
+    RequestMethod,
+} from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { AppxCoreModule, AuthModule, PrismaInterceptor } from '@appxdigital/appx-core';
+import {
+    RequestContextModule,
+    RequestContextMiddleware,
+} from 'nestjs-request-context';
+import { UserModule } from './modules/user/user.module';
+import { PermissionsConfig } from "./config/permissions.config";
+import { createAdminJsModule } from "./backoffice/admin";
+
+@Module({
+    imports: [
+        RequestContextModule,
+        ConfigModule.forRoot({
+            isGlobal: true,
+            expandVariables: true,
+            envFilePath: `.env.${process.env.NODE_ENV || 'development'}`,
+        }),
+        AppxCoreModule.forRoot(PermissionsConfig),
+        AuthModule,
+        UserModule,
+        createAdminJsModule().then((AdminJsModule) => AdminJsModule),
+    ],
+    controllers: [AppController],
+    providers: [
+        AppService,
+        {
+            provide: APP_INTERCEPTOR,
+            useClass: PrismaInterceptor,
+        },
+    ],
+})
+export class AppModule implements NestModule {
+    configure(consumer: MiddlewareConsumer) {
+        consumer
+            .apply(RequestContextMiddleware)
+            .forRoutes({ path: '*', method: RequestMethod.ALL });
+    }
+}

package/templates/adminjs/component-loader.template.js

@@ -0,0 +1,14 @@
+import { dynamicImport } from "./utils";
+
+async function loadComponents() {
+    const { ComponentLoader } = await dynamicImport('adminjs');
+    const componentLoader = new ComponentLoader();
+
+    const Components = {
+        Dashboard: componentLoader.add('dashboard', './components/dashboard'),
+    };
+
+    return { componentLoader, Components };
+}
+
+export const initializeComponents = loadComponents;

package/templates/adminjs/dashboard.template.js

@@ -0,0 +1,37 @@
+import React from 'react';
+
+export const Dashboard = () => {
+
+    return (
+        <div style={{
+            backgroundColor: 'white',
+            borderRadius: '15px',
+            height: '100%',
+            padding: '1rem',
+            margin: '1rem',
+        }}>
+            <h1 style={{ fontSize: "1.5rem", textAlign: "center" }}>Dashboard</h1>
+            <div style={{
+                display: 'flex',
+                gap: '1rem',
+                flexDirection: 'column',
+                textAlign: 'center',
+                marginTop: '3rem',
+                borderRadius: '15px',
+                border: '2px solid gainsboro',
+                maxWidth: '300px',
+                margin: '3rem auto',
+                padding: '1rem',
+            }}>
+                <h2>Customize it!</h2>
+                <p>You can customize your dashboard however you want.</p>
+                <p>Display any data you might find useful.</p>
+                <p>See the number of users or check statistics on graphics</p>
+                <p>Whatever you want to do! Edit it on components/dashboard.</p>
+            </div>
+        </div>
+
+    );
+};
+
+export default Dashboard;

package/templates/adminjs/utils.template.js

@@ -0,0 +1,131 @@
+import { PermissionsConfig } from "../config/permissions.config";
+
+export const dynamicImport = async (packageName: string) =>
+    new Function(`return import('${packageName}')`)();
+
+export const getAdminJSResources = (specific = null) => {
+    const resources = [
+        {
+            name: 'User',
+            options: {},
+        },
+    ];
+
+    return specific ? resources.filter((r) => r.name === specific) : resources;
+};
+
+export function createPermissionHandler(role: string, resource: string, action: string) {
+    const rolePermissions = PermissionsConfig[resource]?.[role];
+
+    if (!rolePermissions) {
+        return () => false;
+    }
+
+    const actionMapping = {
+        list: 'findMany',
+        show: 'findUnique',
+        edit: 'update',
+        delete: 'delete',
+        new: 'create',
+    };
+
+    const mappedAction = actionMapping[action];
+
+    if (!mappedAction || !rolePermissions[mappedAction]) {
+        return () => false;
+    }
+
+    if (rolePermissions[mappedAction] === 'ALL') {
+        return () => true;
+    }
+
+    if (typeof rolePermissions[mappedAction] === 'object') {
+
+        return (requestContext) => {
+            // @ts-ignore
+            const clauses = rolePermissions[mappedAction]?.clauses;
+            if (!clauses) return () => false;
+            return parseClauses(clauses)(requestContext);
+        };
+    }
+
+    return () => false;
+}
+
+const clauseMapping = {
+    '$USER_ID': "id",
+    '$USER_EMAIL': "email",
+};
+
+const parseClauses = (clauses) => {
+    return (requestContext) => {
+        if (!clauses || !Array.isArray(clauses)) return true;
+
+        for (const clause of clauses) {
+            if (clause.type === 'field') {
+                for (const [field, value] of Object.entries(clause.conditions)) {
+                    let actualValue = value;
+
+                    if (typeof value === 'string' && value.startsWith('$')) {
+                        actualValue = requestContext?.currentAdmin[clauseMapping[value]] ?? null;
+                    }
+
+                    if (requestContext.record?.param(field) !== actualValue) {
+                        return false;
+                    }
+                }
+            }
+        }
+        return true;
+    };
+};
+
+
+export const addBasicFilters = (filters) => {
+    return async (request, context) => {
+        for (const [field, value] of Object.entries(filters)) {
+            request.query[`filters.${field}`] = value;
+        }
+        return request;
+    };
+};
+
+export const createActions = () => {
+    return {
+        list: {
+            isAccessible: createIsAccessible('list'),
+        },
+        show: {
+            isAccessible: createIsAccessible('show'),
+        },
+        edit: {
+            isAccessible: createIsAccessible('edit'),
+        },
+        delete: {
+            isAccessible: createIsAccessible('delete'),
+        },
+        new: {
+            isAccessible: createIsAccessible('new'),
+        },
+    };
+};
+
+const createIsAccessible = (action) => {
+    return (context) => {
+        if (!context.currentAdmin) return false;
+        const { role } = context.currentAdmin;
+        return createPermissionHandler(role, context.resource.model.name, action)(context);
+    };
+};
+
+const createBeforeHook = (filters) => {
+    return (request, context) => {
+        if (context.currentAdmin) {
+            request.query.filters = {
+                ...request.query.filters,
+                ...filters,
+            };
+        }
+        return request;
+    };
+};

package/templates/app.module.template.js

@@ -0,0 +1,27 @@
+import {
+    MiddlewareConsumer, Module, NestModule, RequestMethod,
+} from '@nestjs/common';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { ConfigModule } from '@nestjs/config';
+import { AuthModule, PrismaInterceptor, AppxCoreModule } from '@appxdigital/appx-core';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import {
+    RequestContextModule, RequestContextMiddleware,
+} from 'nestjs-request-context'
+import { PermissionsConfig } from './config/permissions.config';
+
+@Module({
+    imports: [RequestContextModule, ConfigModule.forRoot({
+        isGlobal: true, expandVariables: true, envFilePath: `.env.${process.env.NODE_ENV || 'development'}`,
+    }), AppxCoreModule.forRoot(PermissionsConfig), RequestContextModule, AuthModule,], controllers: [AppController], providers: [AppService, {
+        provide: APP_INTERCEPTOR, useClass: PrismaInterceptor,
+    },],
+})
+export class AppModule implements NestModule {
+    configure(consumer: MiddlewareConsumer) {
+        consumer
+            .apply(RequestContextMiddleware)
+            .forRoutes({ path: '*', method: RequestMethod.ALL });
+    }
+}

package/templates/bootstrap.template.js

@@ -0,0 +1,45 @@
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { ConfigService } from '@nestjs/config';
+import * as session from 'express-session';
+import * as passport from 'passport';
+import { PrismaService } from '@appxdigital/appx-core';
+import { ValidationPipe } from '@nestjs/common';
+import { CorePrismaSessionStore } from '@appxdigital/appx-core';
+
+async function bootstrap() {
+    const app = await NestFactory.create(AppModule);
+    const configService = app.get(ConfigService);
+    const prismaService = await app.get(PrismaService);
+    const secret = configService.get<string>('SESSION_SECRET');
+    const port = configService.get<number>('APP_PORT') ?? 3000;
+    const sessionTTL = configService.get<number>('SESSION_TTL') || 86400;
+    const cookiename = configService.get<string>('SESSION_COOKIE_NAME');
+    const isProduction = process.env.NODE_ENV === 'production';
+
+    app.use(
+        session({
+            cookie: {
+                maxAge: sessionTTL * 1000,
+                secure: isProduction,
+                httpOnly: isProduction,
+            },
+            secret: secret ?? 'APPXCORESECRET',
+            resave: false,
+            name: cookiename,
+            saveUninitialized: false,
+            store: new CorePrismaSessionStore(prismaService),
+        }),
+    );
+    app.use(passport.initialize());
+    app.use(passport.session());
+    app.enableCors({
+        origin: 'http://localhost:3000',
+        credentials: true,
+    });
+    app.useGlobalPipes(new ValidationPipe({ transform: true }));
+    await app.listen(port);
+    console.log(`Your application is successfully running on: http://www.localhost:${port} 🚀`);
+}
+
+bootstrap();

package/templates/permissions.config.template.js

@@ -0,0 +1,18 @@
+import { PermissionsConfigType } from '@appxdigital/appx-core';
+
+export const PermissionsConfig: PermissionsConfigType = {
+    User: {
+        ADMIN: {
+            findUnique: 'ALL',
+            findMany: 'ALL',
+            create: 'ALL',
+            update: 'ALL',
+            delete: 'ALL',
+        },
+        CLIENT: {
+            findUnique: {
+                conditions: { id: '$USER_ID' }
+            },
+        }
+    },
+};