create-stb 1.0.6 → 1.2.0

package/README.md

@@ -1,28 +1,34 @@
-# Serverless Typescript Boilerplate by Sam Newhouse
+# create-ntb
+
+## Serverless TypeScript Boilerplate by Sam Newhouse
 
 **A CLI to instantly scaffold a production-ready Serverless TypeScript Boilerplate.**
 
+[![npm version](https://img.shields.io/npm/v/create-stb.svg)](https://www.npmjs.com/package/create-stb)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ---
 
 ## 🚀 Features
 
-- Scaffolds a serverless app with TypeScript, AWS, and DynamoDB.
-- Copies all template files, including configs and sample code.
-- Automatically updates project name in `package.json` and `serverless.yml`.
-- Installs dependencies for you.
-- Simple and fast—no extra configuration.
+- **Fast Setup** - Scaffold a complete serverless app in seconds
+- **TypeScript Ready** - Full TypeScript support with AWS Lambda and DynamoDB
+- **Zero Config** - Automatically updates project name and installs dependencies
+- **Production Ready** - Includes all configs, sample handlers, and best practices
+- **Local Development** - Docker Compose setup for local DynamoDB testing
+- **Modern Stack** - Node.js 20.x, Serverless Framework, and AWS services
 
 ---
 
-## 📦 Installation
+## 📦 Quick Start
 
-**Recommended: Use npx**
+### Using npx (Recommended)
 
 ```bash
 npx create-stb my-app
 ```
 
-Or install globally:
+### Global Installation
 
 ```bash
 npm install -g create-stb
@@ -37,39 +43,63 @@ create-stb my-app
 npx create-stb <project-name>
 ```
 
-This creates a directory `<project-name>` in your current folder.
+This creates a new directory with your project name in the current folder.
 
-Example:
+### Example
 
 ```bash
-npx create-stb pineapple-api
+npx create-stb <project-name>
 cd pineapple-api
 npm run offline
 ```
 
+Your serverless API will be running at `http://localhost:3000`
+
+---
+
+## 🧩 What's Included
+
+### Project Structure
+
+- ✅ **Serverless Configuration** - Pre-configured `serverless.yml` for AWS Lambda
+- ✅ **TypeScript Setup** - Ready-to-use TypeScript configuration
+- ✅ **DynamoDB Integration** - Local DynamoDB with Docker Compose
+- ✅ **Sample Handlers** - Example Lambda functions to get started
+- ✅ **Development Scripts** - `offline`, `build`, `deploy` commands
+- ✅ **Code Quality** - Prettier configuration for consistent formatting
+- ✅ **Environment Config** - `.env.example` for environment variables
+
+### Tech Stack
+
+- **Runtime**: Node.js 20.x
+- **Language**: TypeScript
+- **Framework**: Serverless Framework
+- **Cloud**: AWS (Lambda, DynamoDB, API Gateway)
+- **Local Dev**: serverless-offline, Docker
+
 ---
 
-## 🧩 What You Get
+## 📋 Requirements
 
-- Preconfigured `serverless.yml` for AWS and Node.js 20.x
-- TypeScript-ready project
-- Local DynamoDB scripts and sample handlers
-- Scripts: `offline`, `deploy`, `build`, etc.
-- Clean codebase, ready for development
+- Node.js >= 20.0.0
+- npm >= 10.0.0
+- Git (for cloning the template)
 
 ---
 
 ## 🔗 Links
 
-- [GitHub repository](https://github.com/SamNewhouse/create-stb)
-- [Report issues](https://github.com/SamNewhouse/create-stb/issues)
-- [NPM page](https://www.npmjs.com/package/create-stb)
+- **[GitHub Repository](https://github.com/SamNewhouse/create-stb)**
+- **[NPM Package](https://www.npmjs.com/package/create-stb)**
+- **[Report Issues](https://github.com/SamNewhouse/create-stb/issues)**
+- **[Template Repository](https://github.com/SamNewhouse/create-stb/tree/main/serverless)**
 
 ---
 
 ## 🤝 Contributing
 
-Pull requests, suggestions, and issues are welcome!  
+Contributions are welcome! Please feel free to submit a Pull Request.
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ---
@@ -77,3 +107,15 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 ## 📄 License
 
 MIT © [Sam Newhouse](https://github.com/SamNewhouse)
+
+---
+
+## 💖 Support
+
+If you find this tool helpful, please consider:
+
+- ⭐ Starring the [repository](https://github.com/SamNewhouse/create-stb)
+- 🐛 [Reporting issues](https://github.com/SamNewhouse/create-stb/issues)
+- 💬 Sharing feedback and suggestions
+
+**Thank you for using create-stb!** 🚀

package/dist/create-stb.d.ts

@@ -1,15 +1,77 @@
 #!/usr/bin/env node
+/**
+ * Sanitizes a file path to prevent command injection attacks.
+ * Validates input, blocks dangerous characters, and returns normalized absolute path.
+ * @param inputPath - The path to sanitize
+ * @returns Sanitized absolute path
+ * @throws Error if path is invalid or contains dangerous characters
+ */
+export declare function sanitizePath(inputPath: string): string;
+/**
+ * Checks if the current Node.js version meets the minimum required version.
+ * @param minMajor - Minimum required major version (default: 20)
+ * @throws Error if Node.js version is below the minimum required
+ */
 export declare function checkNodeVersion(minMajor?: number): void;
+/**
+ * Verifies that Git is installed and available on the system.
+ * @throws Error if Git is not installed or cannot be executed
+ */
+export declare function checkGitInstalled(): void;
+/**
+ * Clones the create-stb repository to a temporary directory using sparse checkout
+ * to retrieve only the serverless template folder.
+ * @param tempDir - Temporary directory path for cloning
+ * @returns Path to the cloned serverless template directory
+ * @throws Error if git clone fails or serverless folder is not found
+ */
+export declare function cloneBoilerplate(tempDir: string): string;
+/**
+ * Creates a new project directory, ensuring it doesn't exist or is empty.
+ * @param projectPath - Path to the project directory to create
+ * @throws Error if directory exists and is not empty
+ */
 export declare function createProjectDirectory(projectPath: string): void;
+/**
+ * Recursively copies all files and directories from source to destination,
+ * including dotfiles and nested directories.
+ * @param src - Source directory path
+ * @param dest - Destination directory path
+ */
 export declare function copyDir(src: string, dest: string): void;
+/**
+ * Removes a temporary directory and all its contents.
+ * Does not throw if directory doesn't exist.
+ * @param tempDir - Path to temporary directory to remove
+ */
+export declare function cleanupTemp(tempDir: string): void;
+/**
+ * Updates the package.json file with the new project name and description.
+ * @param projectPath - Path to the project directory
+ * @param projectName - Name for the new project
+ */
 export declare function updatePackageJson(projectPath: string, projectName: string): void;
+/**
+ * Updates the serverless.yml file with the new service name.
+ * @param projectPath - Path to the project directory
+ * @param projectName - Name for the new service
+ */
 export declare function updateServerlessYml(projectPath: string, projectName: string): void;
+/**
+ * Main CLI entry point. Orchestrates the entire project scaffolding process.
+ * @throws Error if any step fails during project creation
+ */
 export declare function main(): Promise<void>;
 declare const _default: {
     checkNodeVersion: typeof checkNodeVersion;
+    checkGitInstalled: typeof checkGitInstalled;
+    sanitizePath: typeof sanitizePath;
+    cloneBoilerplate: typeof cloneBoilerplate;
     createProjectDirectory: typeof createProjectDirectory;
     copyDir: typeof copyDir;
+    cleanupTemp: typeof cleanupTemp;
     updatePackageJson: typeof updatePackageJson;
+    updateServerlessYml: typeof updateServerlessYml;
     main: typeof main;
 };
 export default _default;

package/dist/create-stb.js

@@ -4,16 +4,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizePath = sanitizePath;
 exports.checkNodeVersion = checkNodeVersion;
+exports.checkGitInstalled = checkGitInstalled;
+exports.cloneBoilerplate = cloneBoilerplate;
 exports.createProjectDirectory = createProjectDirectory;
 exports.copyDir = copyDir;
+exports.cleanupTemp = cleanupTemp;
 exports.updatePackageJson = updatePackageJson;
 exports.updateServerlessYml = updateServerlessYml;
 exports.main = main;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const child_process_1 = require("child_process");
-// Progress display helpers
+const os_1 = __importDefault(require("os"));
 function writeLine(msg) {
     const width = process.stdout.columns || 80;
     process.stdout.write(`\r${" ".repeat(width)}\r${msg}`);
@@ -28,13 +32,74 @@ function step(label) {
 function doneStep() {
     clearLine();
 }
-// Ensure required Node version
+/**
+ * Sanitizes a file path to prevent command injection attacks.
+ * Validates input, blocks dangerous characters, and returns normalized absolute path.
+ * @param inputPath - The path to sanitize
+ * @returns Sanitized absolute path
+ * @throws Error if path is invalid or contains dangerous characters
+ */
+function sanitizePath(inputPath) {
+    if (typeof inputPath !== "string" || !inputPath.trim()) {
+        throw new Error("Path must be a non-empty string");
+    }
+    const trimmed = inputPath.trim();
+    // Block input that starts with '-' or '--'
+    if (trimmed.startsWith('-') || trimmed.startsWith('--')) {
+        throw new Error("Invalid path: must not start with '-' or '--'");
+    }
+    // Block dangerous shell metacharacters
+    if (/[`$|;&<>\0]/.test(trimmed)) {
+        throw new Error("Invalid path: contains dangerous characters");
+    }
+    return path_1.default.normalize(path_1.default.resolve(trimmed));
+}
+/**
+ * Checks if the current Node.js version meets the minimum required version.
+ * @param minMajor - Minimum required major version (default: 20)
+ * @throws Error if Node.js version is below the minimum required
+ */
 function checkNodeVersion(minMajor = 20) {
     const [major] = process.version.replace("v", "").split(".");
     if (Number(major) < minMajor)
         throw new Error(`Node.js v${minMajor}+ required`);
 }
-// Create an empty directory (or error if not empty)
+/**
+ * Verifies that Git is installed and available on the system.
+ * @throws Error if Git is not installed or cannot be executed
+ */
+function checkGitInstalled() {
+    try {
+        (0, child_process_1.execFileSync)("git", ["--version"], { stdio: "ignore" });
+    }
+    catch {
+        throw new Error("Git is not installed. Please install git and try again.");
+    }
+}
+/**
+ * Clones the create-stb repository to a temporary directory using sparse checkout
+ * to retrieve only the serverless template folder.
+ * @param tempDir - Temporary directory path for cloning
+ * @returns Path to the cloned serverless template directory
+ * @throws Error if git clone fails or serverless folder is not found
+ */
+function cloneBoilerplate(tempDir) {
+    const repoUrl = "https://github.com/SamNewhouse/create-stb.git";
+    const safeTempDir = sanitizePath(tempDir);
+    const clonePath = path_1.default.join(safeTempDir, "create-stb-temp");
+    const safeClonePath = sanitizePath(clonePath);
+    (0, child_process_1.execFileSync)("git", ["clone", "--depth", "1", "--filter=blob:none", "--sparse", repoUrl, safeClonePath], { stdio: "ignore" });
+    (0, child_process_1.execFileSync)("git", ["sparse-checkout", "set", "serverless"], {
+        cwd: safeClonePath,
+        stdio: "ignore",
+    });
+    return path_1.default.join(safeClonePath, "serverless");
+}
+/**
+ * Creates a new project directory, ensuring it doesn't exist or is empty.
+ * @param projectPath - Path to the project directory to create
+ * @throws Error if directory exists and is not empty
+ */
 function createProjectDirectory(projectPath) {
     if (fs_1.default.existsSync(projectPath)) {
         if (fs_1.default.readdirSync(projectPath).length === 0)
@@ -43,7 +108,12 @@ function createProjectDirectory(projectPath) {
     }
     fs_1.default.mkdirSync(projectPath, { recursive: true });
 }
-// Recursively copy everything, including dotfiles and subfolders
+/**
+ * Recursively copies all files and directories from source to destination,
+ * including dotfiles and nested directories.
+ * @param src - Source directory path
+ * @param dest - Destination directory path
+ */
 function copyDir(src, dest) {
     if (!fs_1.default.existsSync(dest))
         fs_1.default.mkdirSync(dest, { recursive: true });
@@ -58,7 +128,21 @@ function copyDir(src, dest) {
         }
     }
 }
-// Only update basic project info in package.json
+/**
+ * Removes a temporary directory and all its contents.
+ * Does not throw if directory doesn't exist.
+ * @param tempDir - Path to temporary directory to remove
+ */
+function cleanupTemp(tempDir) {
+    if (fs_1.default.existsSync(tempDir)) {
+        fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Updates the package.json file with the new project name and description.
+ * @param projectPath - Path to the project directory
+ * @param projectName - Name for the new project
+ */
 function updatePackageJson(projectPath, projectName) {
     const file = path_1.default.join(projectPath, "package.json");
     if (!fs_1.default.existsSync(file))
@@ -68,6 +152,11 @@ function updatePackageJson(projectPath, projectName) {
     pkg.description = `${projectName} app description`;
     fs_1.default.writeFileSync(file, JSON.stringify(pkg, null, 2));
 }
+/**
+ * Updates the serverless.yml file with the new service name.
+ * @param projectPath - Path to the project directory
+ * @param projectName - Name for the new service
+ */
 function updateServerlessYml(projectPath, projectName) {
     const serverlessPath = path_1.default.join(projectPath, "serverless.yml");
     if (!fs_1.default.existsSync(serverlessPath))
@@ -76,7 +165,10 @@ function updateServerlessYml(projectPath, projectName) {
     content = content.replace(/^service:.*$/m, `service: ${projectName}`);
     fs_1.default.writeFileSync(serverlessPath, content);
 }
-// Main CLI flow
+/**
+ * Main CLI entry point. Orchestrates the entire project scaffolding process.
+ * @throws Error if any step fails during project creation
+ */
 async function main() {
     const name = process.argv[2];
     if (!name) {
@@ -84,39 +176,59 @@ async function main() {
         process.exit(1);
     }
     const projectPath = path_1.default.resolve(process.cwd(), name);
-    const boilerplateSrc = path_1.default.resolve(__dirname, "..", "serverless");
-    step("Checking Node version");
-    checkNodeVersion();
-    doneStep();
-    step("Creating project directory");
-    createProjectDirectory(projectPath);
-    doneStep();
-    step("Copying boilerplate files");
-    copyDir(boilerplateSrc, projectPath);
-    doneStep();
-    step("Updating package.json");
-    updatePackageJson(projectPath, name);
-    doneStep();
-    step("Updating serverless.yml");
-    updateServerlessYml(projectPath, name);
-    doneStep();
-    step("Installing packages");
-    (0, child_process_1.execSync)("npm install --silent", { cwd: projectPath, stdio: "inherit" });
-    doneStep();
-    clearLine();
-    console.log(`\nInstallation complete\n\nNext steps:\n\n  cd ${name}\n  npm run offline\n`);
+    const tempDir = path_1.default.join(os_1.default.tmpdir(), `create-stb-${Date.now()}`);
+    try {
+        step("Checking Node version");
+        checkNodeVersion();
+        doneStep();
+        step("Checking Git installation");
+        checkGitInstalled();
+        doneStep();
+        step("Creating project directory");
+        createProjectDirectory(projectPath);
+        doneStep();
+        step("Downloading boilerplate template");
+        const boilerplateSrc = cloneBoilerplate(tempDir);
+        doneStep();
+        step("Copying boilerplate files");
+        copyDir(boilerplateSrc, projectPath);
+        doneStep();
+        step("Cleaning up temporary files");
+        cleanupTemp(tempDir);
+        doneStep();
+        step("Updating package.json");
+        updatePackageJson(projectPath, name);
+        doneStep();
+        step("Updating serverless.yml");
+        updateServerlessYml(projectPath, name);
+        doneStep();
+        step("Installing packages");
+        (0, child_process_1.execSync)("npm install --silent", { cwd: projectPath, stdio: "inherit" });
+        doneStep();
+        clearLine();
+        console.log(`\n✅ Installation complete!\n\nNext steps:\n\n  cd ${name}\n  npm run offline\n`);
+    }
+    catch (error) {
+        cleanupTemp(tempDir);
+        throw error;
+    }
 }
 exports.default = {
     checkNodeVersion,
+    checkGitInstalled,
+    sanitizePath,
+    cloneBoilerplate,
     createProjectDirectory,
     copyDir,
+    cleanupTemp,
     updatePackageJson,
+    updateServerlessYml,
     main,
 };
 if (require.main === module) {
     main().catch((err) => {
         clearLine();
-        console.error("Error:", err.message);
+        console.error("\n❌ Error:", err.message);
         process.exit(1);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stb",
-  "version": "1.0.6",
+  "version": "1.2.0",
   "description": "A CLI to quickly scaffold a Serverless TypeScript Boilerplate project.",
   "license": "ISC",
   "readme": "README.md",
@@ -16,8 +16,7 @@
     "dist/create-stb.d.ts",
     "README.md",
     "LICENSE",
-    "package.json",
-    "serverless"
+    "package.json"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -27,7 +26,7 @@
   "devDependencies": {
     "@types/jest": "30.0.0",
     "@types/node": "20.19.25",
-    "jest": "^30.2.0",
+    "jest": "30.2.0",
     "prettier": "3.6.2",
     "ts-jest": "29.4.5",
     "typescript": "5.9.3"

package/serverless/.env.example

@@ -1,14 +0,0 @@
-# AWS credentials (dummy for local, ignored by DynamoDB Local)
-AWS_ACCESS_KEY_ID=
-AWS_SECRET_ACCESS_KEY=
-AWS_REGION=eu-west-2
-AWS_REGION_FALLBACK=eu-west-1
-
-# DynamoDB Setup
-DYNAMODB_ENDPOINT=http://localhost:8000
-
-# If you use other secrets (JWT, third party APIs etc.), add those here too:
-JWT_SECRET=
-
-# Current environment/stage
-STAGE=dev

package/serverless/.prettierignore

@@ -1,20 +0,0 @@
-# Ignore build output
-.build
-dist
-coverage
-
-# Node
-node_modules
-
-# Dependency lockfiles (if you don't want Prettier to format them)
-package-lock.json
-yarn.lock
-
-# Serverless, system, IDE, or OS files
-.serverless
-.DS_Store
-.env
-*.log
-
-# Lambdas' bundles (if any)
-bundle-*.js

package/serverless/.prettierrc

@@ -1,6 +0,0 @@
-{
-  "semi": true,
-  "singleQuote": false,
-  "printWidth": 100,
-  "trailingComma": "all"
-}

package/serverless/README.md

@@ -1,36 +0,0 @@
-# Serverless Typescript Boilerplate
-
-Minimalist project template to jump start a Serverless application in TypeScript.
-
-## Keys features
-
-The current Serverless Starter Kit adds a light layer on top of the Serverless framework with modern JavaScript tools:
-
-- **TypeScript** Support.
-- **Offline** mode
-- Formatting with Prettier to enforce a consistent code style.
-
-## Services
-
-Currently, the boilerplate is built and tested on AWS using the following services.
-
-- AWS Lambda
-
-## Quick start
-
-```
-npm install
-npm run offline
-```
-
-### Deployment
-
-Make sure you have AWS Cli configured
-
-```bash
-npm run deploy
-```
-
-## Serverless plugins
-
-- [serverless-offline](https://github.com/dherault/serverless-offline): run your services offline for e.g. testing

package/serverless/docker-compose.yml

@@ -1,36 +0,0 @@
-version: "3.8"
-services:
-  dynamodb-local:
-    image: amazon/dynamodb-local
-    container_name: dynamodb-local
-    restart: unless-stopped
-    ports:
-      - "8000:8000"
-    command: "-jar DynamoDBLocal.jar -inMemory -sharedDb"
-    working_dir: /home/dynamodblocal
-    volumes:
-      - dynamodb_data:/home/dynamodblocal/data
-    environment:
-      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-dummy}
-      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-dummy}
-      - AWS_REGION=${AWS_REGION:-eu-west-2}
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8000/"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-  dynamodb-admin:
-    image: aaronshaf/dynamodb-admin
-    ports:
-      - "8001:8001"
-    environment:
-      - DYNAMO_ENDPOINT=${DYNAMO_ENDPOINT:-http://dynamodb-local:8000}
-      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-dummy}
-      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-dummy}
-      - AWS_REGION=${AWS_REGION:-eu-west-2}
-    links:
-      - dynamodb-local
-
-volumes:
-  dynamodb_data: