nebula-starter-kit 0.0.1

package/README.md

@@ -0,0 +1,107 @@
+# Nebula Logix Starter Kit
+
+This is a downloadable & installable AWS production-ready AI-enabled package that serves essentially as a Software As A Service (SaaS), that users/clients can setup quickly in their AWS environment.
+
+## Components
+- cli/ directory to generate a full-fledged deployable application with a variety of modules and functionalities to choose from.
+- templates/ directory containing the base NestJS application template.
+- modules/ directory for the modules options.
+
+## Features
+- NestJS framework for building scalable and maintainable server-side applications.
+- AWS Lambda integration for serverless deployment.
+- Pre-configured TypeScript support.
+- Sample API endpoint to demonstrate functionality.
+
+## Prerequisites
+- Node.js (version 14 or higher)
+- npm (version 6 or higher)
+- AWS CLI configured with your credentials
+
+## Setup
+
+```bash
+Navigate to the 'cli' directory
+
+$ RUN cd cli
+$ RUN npm install
+$ RUN nebula create <app-name>
+```
+
+## Deployment
+
+```bash
+Navigate to the app directory
+
+$ RUN cd <app-name>
+$ RUN serverless deploy --config infra/api/serverless.yml
+$ COPY the "ServiceEndpoint" value from the terminal output and update the NEXT_PUBLIC_API_URL of the .env.local of the ui directory
+$ RUN npm run deploy
+
+$ Navigate to the "WebsiteURL" of the buckets on the terminal output
+```
+
+## Teardown
+
+```bash
+Navigate to the app directory
+
+$ RUN cd <app-name>
+$ RUN npm run teardown
+```
+
+## Common Errors
+
+```
+❌ Not a nebula project
+Usage: Run nebula command only in specified locations
+```
+
+```
+❌ Unknown command
+Available commands
+1. nebula create <app-name>
+2. nebula add service <service-name>
+3. nebula list services
+```
+
+```
+❌ Services directory not found
+```
+
+```
+❌ Modules directory not found
+```
+
+```
+Example of the folder structure of the starter kit and an nlx app generated.
+The ui directory contains the NextJS React App
+
+The infra contains the api gateway, s3 buckets and other associated infrastructure setup.
+
+The services contains the individual service modules as determined by the user.
+
+The core has the database, authentication and other related features.
+```
+
+```
+├── cli
+│   ├── dist
+│   ├── nebula.json
+│   ├── package-lock.json
+│   ├── package.json
+│   ├── src
+│   ├── templates
+│   └── tsconfig.json
+├── nlx
+│   ├── core
+│   ├── infra
+│   ├── nebula.json
+│   ├── package.json
+│   ├── serverless-compose.yml
+│   ├── services
+│   ├── tsconfig.json
+│   └── ui
+└── README.md
+
+```

package/dist/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const run_1 = require("./run");
+(0, run_1.run)().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+});

package/dist/run.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const child_process_1 = require("child_process");
+const appName_1 = require("./utils/appName");
+const deployNow_1 = require("./utils/deployNow");
+const telemetryAddon_1 = require("./utils/telemetryAddon");
+const generateFiles_1 = require("./utils/generateFiles");
+const generateSchemas_1 = require("./utils/generateSchemas");
+const ROOT = process.cwd();
+const region = (0, telemetryAddon_1.getAwsRegion)();
+console.log('\nregion', region, '\n');
+let appNamePlaceHolder;
+async function run() {
+    const appName = await (0, appName_1.promptAppName)();
+    appNamePlaceHolder = appName;
+    console.log('appNamePlaceHolder', appNamePlaceHolder);
+    const OUTPUT = path_1.default.join(ROOT, `../${appName}`);
+    if (await fs_extra_1.default.pathExists(OUTPUT)) {
+        console.log(`🧹 Cleaning ${appName} folder...\n`);
+        await fs_extra_1.default.remove(OUTPUT);
+    }
+    await fs_extra_1.default.ensureDir(OUTPUT);
+    console.log(`📁 Fresh ${appName} created\n`);
+    const { selectionMode } = await inquirer_1.default.prompt([
+        {
+            type: 'list',
+            name: 'selectionMode',
+            message: 'How would you like to define services?',
+            choices: ['Select from available modules', 'Type service names manually'],
+        },
+    ]);
+    let selectedServices = [];
+    const modulesDir = path_1.default.join(ROOT, './templates/modules');
+    if (!fs_extra_1.default.existsSync(modulesDir)) {
+        console.log(`❌ Modules directory not found\n`);
+        throw new Error('Modules directory not found');
+        // process.exit(1);
+    }
+    if (selectionMode === 'Select from available modules') {
+        const { services } = await inquirer_1.default.prompt([
+            {
+                type: 'checkbox',
+                name: 'services',
+                message: 'Select services',
+                choices: fs_extra_1.default.readdirSync(path_1.default.join(ROOT, './templates/modules')),
+            },
+        ]);
+        selectedServices = services;
+    }
+    if (selectionMode === 'Type service names manually') {
+        // TODO Validate service names for casing and other formats
+        const { servicesInput } = await inquirer_1.default.prompt([
+            {
+                type: 'input',
+                name: 'servicesInput',
+                message: 'Enter service names (comma separated, e.g. products,orders,users):',
+            },
+        ]);
+        const services = servicesInput
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        selectedServices = services;
+    }
+    // Move core module into app
+    const coreDir = path_1.default.join(OUTPUT, 'core');
+    await fs_extra_1.default.ensureDir(coreDir);
+    fs_extra_1.default.copySync(path_1.default.join(ROOT, 'templates/core'), coreDir);
+    // Move UI module into app
+    const uiDir = path_1.default.join(OUTPUT, 'ui');
+    await fs_extra_1.default.ensureDir(uiDir);
+    fs_extra_1.default.copySync(path_1.default.join(ROOT, 'templates/ui'), uiDir);
+    // Generate nebula json
+    (0, generateFiles_1.generateNebulaJson)(appName, selectedServices, OUTPUT);
+    (0, generateSchemas_1.generateSchemas)(OUTPUT);
+    // Generate root lambda
+    (0, generateFiles_1.generateRootLambda)(appName, selectedServices, OUTPUT);
+    // Generate serverless.yml for infra/api gateway
+    await (0, generateFiles_1.generateInfraApiFile)(appName, OUTPUT);
+    // Generate serverless.yml for infra/buckets
+    await (0, generateFiles_1.generateInfraBucketFile)(appName, OUTPUT);
+    // Generate serverless.yml for infra/cognito
+    await (0, generateFiles_1.generateInfraCognitoFile)(appName, OUTPUT);
+    // Move package.json into app
+    await fs_extra_1.default.copy(path_1.default.join(ROOT, 'templates/package.json'), path_1.default.join(OUTPUT, 'package.json'));
+    // Move tsconfig into app
+    await fs_extra_1.default.copy(path_1.default.join(ROOT, 'templates/tsconfig.json'), path_1.default.join(OUTPUT, 'tsconfig.json'));
+    // Handle content for services
+    await (0, generateFiles_1.generateServerlessFiles)(selectedServices, ROOT, OUTPUT, appNamePlaceHolder);
+    // Create env file for Root environment variables
+    (0, generateFiles_1.generateRootEnv)(OUTPUT);
+    // Create env file for NextJS environment variables
+    (0, generateFiles_1.generateNextJSEnv)(appName, uiDir, selectedServices);
+    // Prompt telemetry
+    await (0, telemetryAddon_1.promptTelemetry)(appName, selectedServices);
+    // 7. Install deps & deploy
+    const deployNow = await (0, deployNow_1.promptDeployNow)();
+    if (deployNow) {
+        (0, child_process_1.execSync)('npm install && npm run deploy', {
+            cwd: OUTPUT,
+            stdio: 'inherit',
+        });
+    }
+}

package/dist/utils/addService.js

@@ -0,0 +1,204 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverlessTemplate = void 0;
+exports.addService = addService;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const replaceServiceNames_1 = require("./replaceServiceNames");
+const telemetryAddon_1 = require("./telemetryAddon");
+const yaml_1 = __importDefault(require("yaml"));
+const generateFiles_1 = require("./generateFiles");
+const generateSchemas_1 = require("./generateSchemas");
+const region = (0, telemetryAddon_1.getAwsRegion)();
+function getServicePorts(service, appName) {
+    const ROOT = process.cwd();
+    let config;
+    let nebulaPath;
+    let httpPort = 3001;
+    let lambdaPort = 3001;
+    if (!appName) {
+        nebulaPath = path_1.default.join(ROOT, 'nebula.json');
+        if (!fs_extra_1.default.existsSync(nebulaPath)) {
+            throw new Error('Not a Nebula project');
+        }
+        config = fs_extra_1.default.readJsonSync(nebulaPath);
+        appName = config.name;
+        const servicesCount = config.services.length;
+        httpPort = 3001 + servicesCount * 2;
+        lambdaPort = httpPort + 1;
+    }
+    else {
+        nebulaPath = path_1.default.join(ROOT, `../${appName}`, 'nebula.json');
+        if (!fs_extra_1.default.existsSync(nebulaPath)) {
+            throw new Error('Not a Nebula project');
+        }
+        config = fs_extra_1.default.readJsonSync(nebulaPath);
+        const index = config.services.indexOf(service);
+        httpPort = 3001 + index * 2;
+        lambdaPort = httpPort + 1;
+    }
+    return { httpPort, lambdaPort, appName };
+}
+const serverlessTemplate = (service, appName) => {
+    const { httpPort, lambdaPort, appName: nameTag, } = getServicePorts(service, appName);
+    console.log('offline port values for service:', service, httpPort, lambdaPort, nameTag);
+    return `service: ${nameTag}-${service}
+
+provider:
+  name: aws
+  runtime: nodejs20.x
+  region: ${region}
+  stage: \${opt:stage, 'dev'}
+  memorySize: 256
+  timeout: 30
+
+  environment:
+    REGION: us-east-1
+    COGNITO_CLIENT_ID: \${param:CognitoClientId, env:COGNITO_CLIENT_ID}
+    COGNITO_USER_POOL_ID: \${param:CognitoUserPoolId, env:COGNITO_USER_POOL_ID}
+
+  apiGateway:
+    restApiId: \${param:ApiGatewayRestApiId, null} 
+    restApiRootResourceId: \${param:ApiGatewayRootResourceId, null}
+
+  stackTags:
+    CostCenter: \${self:provider.stage}-\${aws:accountId}
+
+  iam:
+    role:
+      statements:
+        # ✅ Bedrock permission
+        - Effect: Allow
+          Action:
+            - bedrock:InvokeModel
+          Resource:
+            - arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-haiku-20240307-v1:0
+
+        # ✅ Cognito permission
+        - Effect: Allow
+          Action:
+            - cognito-idp:ListUsers
+          Resource:
+            - arn:aws:cognito-idp:\${self:provider.region}:\${aws:accountId}:userpool/\${param:CognitoUserPoolId, env:COGNITO_USER_POOL_ID}
+
+        # ✅ DynamoDB permission
+        - Effect: Allow
+          Action:
+            - dynamodb:DescribeTable
+            - dynamodb:CreateTable
+            - dynamodb:GetItem
+            - dynamodb:PutItem
+            - dynamodb:UpdateItem
+            - dynamodb:Query
+            - dynamodb:Scan
+          Resource:
+            - arn:aws:dynamodb:\${self:provider.region}:*:table/*
+
+        # ✅ Cloudformation permission
+        - Effect: Allow
+          Action:
+            - cloudformation:ListStacks
+            - cloudformation:DescribeStacks
+          Resource: "*"
+
+custom:
+  serverless-offline:
+    noPrependStageInUrl: true
+    httpPort: ${httpPort}
+    lambdaPort: ${lambdaPort}
+
+build:
+  esbuild:
+    bundle: true
+    minify: false
+    sourcemap: true
+    keepNames: true
+    target: node20
+    format: cjs
+
+    external:
+      - aws-sdk
+      - "@nestjs/microservices"
+      - "@nestjs/microservices/microservices-module"
+      - "@nestjs/websockets"
+      - "@nestjs/websockets/socket-module"
+      - "class-transformer/storage"
+
+functions:
+  app:
+    handler: src/lambda.handler
+    events:
+      - http:
+          path: /${service}/{proxy+}
+          method: any
+          cors: true
+
+package:
+  individually: true
+    
+plugins:
+  - serverless-offline
+`;
+};
+exports.serverlessTemplate = serverlessTemplate;
+async function addService(serviceName, selectedServices, appName) {
+    const ROOT = process.cwd();
+    const nebulaPath = path_1.default.join(ROOT, 'nebula.json');
+    if (!fs_extra_1.default.existsSync(nebulaPath)) {
+        throw new Error('Not a Nebula project');
+    }
+    const config = fs_extra_1.default.readJsonSync(nebulaPath);
+    if (config.services.includes(serviceName)) {
+        console.log('Service already exists');
+        return;
+    }
+    // create folder
+    const serviceDir = path_1.default.join(ROOT, 'services', serviceName);
+    await fs_extra_1.default.ensureDir(serviceDir);
+    // copy base nest template
+    fs_extra_1.default.copySync(path_1.default.join(ROOT, '../cli/templates/service'), serviceDir);
+    // update service names
+    await (0, replaceServiceNames_1.replaceServiceNames)(serviceDir, serviceName, appName);
+    // Generate serverless.yml per service
+    await fs_extra_1.default.writeFile(path_1.default.join(serviceDir, 'serverless.yml'), (0, exports.serverlessTemplate)(serviceName));
+    // Regenerate root lambda
+    (0, generateFiles_1.generateRootLambda)(config.name, [...selectedServices, serviceName], ROOT);
+    // Generate root serverless-compose.yml
+    const composePath = path_1.default.join(ROOT, 'serverless-compose.yml');
+    let parsed;
+    if (fs_extra_1.default.existsSync(composePath)) {
+        parsed = yaml_1.default.parse(await fs_extra_1.default.readFile(composePath, 'utf8'));
+    }
+    else {
+        parsed = {
+            services: {
+                api: { path: 'infra/api' },
+                cognito: { path: 'infra/cognito' },
+                buckets: { path: 'infra/buckets' },
+            },
+        };
+    }
+    selectedServices.push(serviceName);
+    for (const service of selectedServices) {
+        if (!parsed.services[service]) {
+            parsed.services[service] = {
+                path: `services/${service}`,
+                params: {
+                    ApiGatewayRestApiId: '${api.ApiGatewayRestApiId}',
+                    ApiGatewayRootResourceId: '${api.ApiGatewayRootResourceId}',
+                    CognitoClientId: '${cognito.CognitoClientId}',
+                    CognitoUserPoolId: '${cognito.CognitoUserPoolId}',
+                },
+            };
+        }
+    }
+    await fs_extra_1.default.writeFile(composePath, yaml_1.default.stringify(parsed));
+    // update config
+    config.services.push(serviceName);
+    fs_extra_1.default.writeJsonSync(nebulaPath, config, { spaces: 2 });
+    (0, generateSchemas_1.generateSchemas)(ROOT);
+    console.log(`✅ Service ${serviceName} created & added`);
+}

package/dist/utils/appName.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptAppName = promptAppName;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const listServices_1 = require("./listServices");
+const addService_1 = require("./addService");
+async function promptAppName() {
+    const [, , command, argAppName] = process.argv;
+    const commands = ['create', 'add', 'list'];
+    const addListCommands = ['add', 'list'];
+    const nebulaConfig = path_1.default.join(process.cwd(), 'nebula.json');
+    if (!fs_extra_1.default.existsSync(nebulaConfig)) {
+        console.log(`❌ Not a nebula project\nUsage: Run nebula command only in specified locations\n`);
+        process.exit(1);
+    }
+    const config = fs_extra_1.default.readJsonSync(nebulaConfig);
+    if (!commands.includes(command)) {
+        console.log(`❌ Unknown command\nAvailable commands\n1. nebula create <app-name>\n2. nebula add service <service-name>\n3. nebula list services\n`);
+        process.exit(1);
+    }
+    if (addListCommands.includes(command)) {
+        if (!config.services) {
+            console.log('❌ Services directory not found\n');
+            process.exit(1);
+        }
+        else {
+            switch (command) {
+                case 'add':
+                    if (!process.argv[4]) {
+                        console.log(`❌ Missing service name\nUsage: nebula add service <service-name>\n`);
+                        process.exit(1);
+                    }
+                    if (argAppName === 'service')
+                        await (0, addService_1.addService)(process.argv[4], config.services, `${config.name}`);
+                    process.exit(1);
+                case 'list':
+                    if (argAppName !== 'services') {
+                        console.log(`❌ Incorrect CLI command\nUsage: nebula list services\n`);
+                        process.exit(1);
+                    }
+                    if (argAppName === 'services')
+                        (0, listServices_1.listServices)();
+                    process.exit(1);
+            }
+        }
+    }
+    if (!config.services) {
+        if (config.name !== 'cli') {
+            console.log(`❌ Incorrect CLI directory\n`);
+            process.exit(1);
+        }
+    }
+    let appName = argAppName;
+    // If app name not provided → prompt
+    if (!appName) {
+        const { appName: promptedName } = await inquirer_1.default.prompt([
+            {
+                type: 'input',
+                name: 'appName',
+                message: 'Enter application name:',
+                default: 'my-starterkit-app',
+                validate: (input) => /^[a-z0-9-]+$/.test(input)
+                    ? true
+                    : 'Use lowercase letters, numbers, and hyphens only',
+            },
+        ]);
+        return promptedName;
+    }
+    return appName;
+}

package/dist/utils/deployNow.js

@@ -0,0 +1,18 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptDeployNow = promptDeployNow;
+const inquirer_1 = __importDefault(require("inquirer"));
+async function promptDeployNow() {
+    const { deployNow } = await inquirer_1.default.prompt([
+        {
+            type: 'confirm',
+            name: 'deployNow',
+            message: 'Deploy to AWS using SAM now?',
+            default: false,
+        },
+    ]);
+    return deployNow;
+}