create-stb 1.0.5 → 1.1.0

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.5",
+  "version": "1.1.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: