@actuallyjamez/elysian 0.3.0 → 0.5.0

package/README.md

@@ -1,23 +1,31 @@
 # elysian
 
-Automatic Lambda bundler for [Elysia](https://elysiajs.com/) with AWS API Gateway and Terraform integration.
+> Automatic Lambda bundler for [Elysia](https://elysiajs.com/) with AWS API Gateway and Terraform integration.
 
 ## Features
 
 - **Zero-config Lambda handlers** - Just export your Elysia routes as default, handlers are auto-generated
+- **Interactive init wizard** - Sets up fresh or existing projects with smart defaults
+- **Package manager detection** - Automatically detects bun/npm/pnpm/yarn from lockfiles
 - **Automatic OpenAPI aggregation** - All routes are aggregated into a single OpenAPI spec endpoint
-- **Terraform integration** - Generates `tfvars` files for seamless infrastructure deployment
+- **Smart Terraform integration** - Generates modular Terraform files that won't overwrite your existing config
 - **Type-safe configuration** - Full TypeScript support with `defineConfig()`
 - **Watch mode** - Fast rebuilds during development
 
 ## Installation
 
 ```bash
-# Configure GitHub registry for @actuallyjamez scope
-echo "@actuallyjamez:registry=https://npm.pkg.github.com" >> .npmrc
-
-# Install
+# With bun (recommended)
 bun add elysia @actuallyjamez/elysian
+
+# With npm
+npm install elysia @actuallyjamez/elysian
+
+# With pnpm
+pnpm add elysia @actuallyjamez/elysian
+
+# With yarn
+yarn add elysia @actuallyjamez/elysian
 ```
 
 ## Quick Start
@@ -25,13 +33,41 @@ bun add elysia @actuallyjamez/elysian
 ### 1. Initialize your project
 
 ```bash
-bunx @actuallyjamez/elysian init --name my-api
+# Interactive wizard - prompts for everything you need
+elysian init
 ```
 
-This creates:
-- `elysian.config.ts` - Configuration file
-- `src/lambdas/hello.ts` - Example lambda
-- `terraform/main.tf` - Terraform infrastructure
+The wizard will:
+- Ask where to create the project (default: current directory)
+- Detect your package manager automatically
+- Create all necessary files
+- Install dependencies (fresh projects only)
+
+**Fresh project example:**
+```
+? Where would you like to create your project? my-api
+✔ Created directory: my-api
+
+ℹ Creating new elysian project: my-api
+
+? Package manager: bun
+✔ Created package.json
+✔ Created elysian.config.ts
+✔ Created src/lambdas/hello.ts
+✔ Created terraform/providers.tf
+...
+```
+
+**Existing project example:**
+```
+ℹ Adding elysian to: my-existing-app
+
+ℹ Detected package manager: bun
+? Install dependencies? Yes
+✔ Created elysian.config.ts
+✔ Updated terraform/variables.tf
+...
+```
 
 ### 2. Write your lambdas
 
@@ -54,16 +90,16 @@ export default createLambda()
   });
 ```
 
-**That's it!** No need to export a handler - the bundler wraps your default export automatically.
+**That's it!** No need to export a handler - bundler wraps your default export automatically.
 
 ### 3. Build
 
 ```bash
 # Development build
-bunx elysian build
+elysian build
 
 # Production build (minified)
-bunx elysian build --prod
+elysian build --prod
 ```
 
 ### 4. Deploy
@@ -82,30 +118,32 @@ Create `elysian.config.ts` in your project root:
 import { defineConfig } from "@actuallyjamez/elysian";
 
 export default defineConfig({
-  // Required
-  apiName: "my-api",
+  // Required: Used for naming your AWS resources
+  name: "my-api",
 
-  // Optional (showing defaults)
+  // Optional: Lambda source directory (default: "src/lambdas")
   lambdasDir: "src/lambdas",
+
+  // Optional: Build output directory (default: "dist")
   outputDir: "dist",
 
-  // OpenAPI configuration
+  // Optional: OpenAPI configuration (default: enabled)
+  // Note: title and version have smart defaults
   openapi: {
     enabled: true,
-    title: "My API",
-    version: "1.0.0",
+    // title defaults to `name` if not provided
+    // version defaults to package.json version if not provided
     description: "API description",
   },
 
-  // Terraform output configuration
+  // Optional: Terraform output directory (default: "terraform")
   terraform: {
     outputDir: "terraform",
-    tfvarsFilename: "api-routes.auto.tfvars", // Won't overwrite your existing tfvars
   },
 
-  // Lambda defaults (used in generated tfvars)
+  // Optional: Lambda defaults
   lambda: {
-    runtime: "nodejs20.x",
+    runtime: "nodejs22.x",
     memorySize: 256,
     timeout: 30,
   },
@@ -114,37 +152,66 @@ export default defineConfig({
 
 ## CLI Commands
 
+### `elysian init`
+
+Interactive wizard to initialize a new elysian project.
+
+```bash
+# Initialize in current directory
+elysian init
+
+# Initialize in subdirectory (creates it if needed)
+elysian init
+# Answer: my-new-api
+
+# Force overwrite existing files
+elysian init --force
+```
+
+**What it creates (fresh project):**
+- `package.json` - With build scripts
+- `tsconfig.json` - TypeScript configuration
+- `.gitignore` - Ignores node_modules, dist, terraform state
+- `elysian.config.ts` - Elysian configuration
+- `src/lambdas/hello.ts` - Example lambda
+- `terraform/providers.tf` - AWS provider configuration
+- `terraform/variables.tf` - Terraform variables
+- `terraform/main.tf` - Lambda and API Gateway resources
+- `terraform/outputs.tf` - API endpoint output
+
+**What it does (existing project):**
+- Detects package manager from lockfiles
+- Creates `elysian.config.ts` (doesn't overwrite if exists)
+- Creates example lambda only if no `.ts` files in `src/lambdas/`
+- Smart-appends to existing Terraform files (won't overwrite your config)
+
 ### `elysian build`
 
 Build all lambdas for deployment.
 
 ```bash
-bunx elysian build          # Development build
-bunx elysian build --prod   # Production build (minified)
+# Development build
+elysian build
+
+# Production build (minified, no sourcemaps)
+elysian build --prod
 ```
 
 **Output:**
 - `dist/*.js` - Bundled lambda code
 - `dist/*.zip` - Lambda deployment packages
 - `dist/manifest.json` - Route manifest (for debugging)
-- `terraform/api-routes.auto.tfvars` - Terraform variables
 
 ### `elysian dev`
 
 Watch mode for development - rebuilds on file changes.
 
 ```bash
-bunx elysian dev              # Watch with packaging
-bunx elysian dev --no-package # Skip zip creation (faster)
-```
+# Watch with packaging
+elysian dev
 
-### `elysian init`
-
-Initialize a new project with example files.
-
-```bash
-bunx elysian init --name my-api
-bunx elysian init --force  # Overwrite existing files
+# Watch without zip creation (faster)
+elysian dev --no-package
 ```
 
 ### `elysian generate-iac`
@@ -152,15 +219,28 @@ bunx elysian init --force  # Overwrite existing files
 Regenerate Terraform files without rebuilding lambdas.
 
 ```bash
-bunx elysian generate-iac
+elysian generate-iac
 ```
 
+**Smart Terraform file handling:**
+- `providers.tf` - Adds AWS provider if missing
+- `variables.tf` - Adds missing variables only
+- `main.tf` - Adds Lambda/API Gateway resources if missing
+- `outputs.tf` - Adds API endpoint output if missing
+
 ## How It Works
 
 ### 1. Route Discovery
 
 The bundler scans your `lambdasDir` for `.ts` files. Each file becomes a separate Lambda function.
 
+```
+src/lambdas/
+├── users.ts    → users.zip → AWS Lambda (users-api)
+├── posts.ts    → posts.zip → AWS Lambda (posts-api)
+└── auth.ts     → auth.zip  → AWS Lambda (auth-api)
+```
+
 ### 2. Handler Injection
 
 When you export an Elysia app as default:
@@ -187,7 +267,14 @@ An `__openapi__` lambda is automatically generated that imports all your routes
 
 ### 4. Terraform Integration
 
-The generated `tfvars` file contains:
+The generated Terraform files are modular and won't overwrite your existing configuration:
+
+- **providers.tf** - AWS provider with version `~> 6.0`
+- **variables.tf** - All variables (region, lambda config, routes)
+- **main.tf** - API Gateway, Lambda, IAM resources
+- **outputs.tf** - API endpoint URL
+
+The `terraform/api-routes.auto.tfvars` file is auto-generated on each build with:
 - List of Lambda names
 - Route-to-Lambda mappings (with API Gateway path format)
 - Lambda configuration defaults
@@ -197,22 +284,28 @@ The generated `tfvars` file contains:
 ```
 my-api/
 ├── elysian.config.ts         # Configuration
+├── package.json              # Dependencies & scripts
+├── tsconfig.json            # TypeScript config
+├── .gitignore               # Git ignore patterns
 ├── src/
 │   └── lambdas/
-│       ├── users.ts          # → users.zip Lambda
-│       ├── posts.ts          # → posts.zip Lambda
-│       └── auth.ts           # → auth.zip Lambda
-├── dist/                     # Build output
-│   ├── users.js
-│   ├── users.zip
-│   ├── posts.js
-│   ├── posts.zip
-│   ├── __openapi__.js        # Auto-generated
+│       ├── users.ts          # → my-api-users.zip Lambda
+│       ├── posts.ts          # → my-api-posts.zip Lambda
+│       └── auth.ts           # → my-api-auth.zip Lambda
+├── dist/                    # Build output
+│   ├── my-api-users.js
+│   ├── my-api-users.zip
+│   ├── my-api-posts.js
+│   ├── my-api-posts.zip
+│   ├── __openapi__.js       # Auto-generated
 │   ├── __openapi__.zip
 │   └── manifest.json
 └── terraform/
-    ├── main.tf
-    └── api-routes.auto.tfvars  # Auto-generated
+    ├── providers.tf          # AWS provider
+    ├── variables.tf         # Terraform variables
+    ├── main.tf             # Resources (Lambda, API Gateway, IAM)
+    ├── outputs.tf          # Outputs
+    └── api-routes.auto.tfvars  # Auto-generated on build
 ```
 
 ## Requirements

package/dist/cli/commands/build.js

@@ -57,7 +57,7 @@ export const buildCommand = defineCommand({
             console.log(`  ${pc.red("✗")} ${error instanceof Error ? error.message : error}`);
             process.exit(1);
         }
-        const apiName = config.apiName;
+        const name = config.name;
         const lambdasDir = join(process.cwd(), config.lambdasDir);
         const outputDir = join(process.cwd(), config.outputDir);
         const terraformDir = join(process.cwd(), config.terraform.outputDir);
@@ -86,7 +86,7 @@ export const buildCommand = defineCommand({
         const buildResults = [];
         for (const file of lambdaFiles) {
             const name = file.replace(/\.ts$/, "");
-            const bundleName = getLambdaBundleName(apiName, name);
+            const bundleName = getLambdaBundleName(name, name);
             const inputPath = join(lambdasDir, file);
             // Create wrapper entry that imports the original and exports handler
             const wrapperPath = join(tempDir, `${name}-wrapper.ts`);
@@ -112,7 +112,7 @@ export const buildCommand = defineCommand({
         const packageSizes = new Map();
         for (const file of lambdaFiles) {
             const name = file.replace(/\.ts$/, "");
-            const bundleName = getLambdaBundleName(apiName, name);
+            const bundleName = getLambdaBundleName(name, name);
             const jsPath = join(outputDir, `${bundleName}.js`);
             const result = await packageLambda(bundleName, jsPath, outputDir);
             if (!result.success) {
@@ -129,7 +129,7 @@ export const buildCommand = defineCommand({
         // Generate manifest
         console.log(`  ${pc.green("✓")} Generating manifest...`);
         try {
-            const manifest = await generateManifest(lambdaFiles, outputDir, config.openapi.enabled, apiName);
+            const manifest = await generateManifest(lambdaFiles, outputDir, config.openapi.enabled, name);
             // Write JSON manifest
             const manifestPath = join(outputDir, "manifest.json");
             await writeManifest(manifest, manifestPath);
@@ -145,8 +145,8 @@ export const buildCommand = defineCommand({
             const routesByLambda = new Map();
             for (const route of manifest.routes) {
                 // Extract display name (original name) from bundle name
-                const displayName = route.lambda.startsWith(`${apiName}-`)
-                    ? route.lambda.slice(apiName.length + 1)
+                const displayName = route.lambda.startsWith(`${name}-`)
+                    ? route.lambda.slice(name.length + 1)
                     : route.lambda;
                 const existing = routesByLambda.get(displayName) || [];
                 existing.push(route);

package/dist/cli/commands/dev.js

@@ -32,7 +32,7 @@ export const devCommand = defineCommand({
             consola.error(error instanceof Error ? error.message : error);
             process.exit(1);
         }
-        const apiName = config.apiName;
+        const name = config.name;
         const lambdasDir = join(process.cwd(), config.lambdasDir);
         const outputDir = join(process.cwd(), config.outputDir);
         const tempDir = join(outputDir, "__temp__");
@@ -51,7 +51,7 @@ export const devCommand = defineCommand({
         // Build function for a single lambda
         async function buildSingleLambda(filename) {
             const name = filename.replace(/\.ts$/, "");
-            const bundleName = getLambdaBundleName(apiName, name);
+            const bundleName = getLambdaBundleName(name, name);
             const inputPath = join(lambdasDir, filename);
             // Create wrapper entry
             const wrapperPath = join(tempDir, `${name}-wrapper.ts`);

package/dist/cli/commands/generate-iac.js

@@ -25,7 +25,7 @@ export const generateIacCommand = defineCommand({
             consola.error(error instanceof Error ? error.message : error);
             process.exit(1);
         }
-        const apiName = config.apiName;
+        const name = config.name;
         const outputDir = join(process.cwd(), config.outputDir);
         const terraformDir = join(process.cwd(), config.terraform.outputDir);
         // Check that build output exists
@@ -45,14 +45,14 @@ export const generateIacCommand = defineCommand({
         // The manifest generator will re-add the prefix
         const lambdaFiles = jsFiles.map((f) => {
             const bundleName = f.replace(/\.js$/, "");
-            const originalName = getOriginalLambdaName(apiName, bundleName);
+            const originalName = getOriginalLambdaName(name, bundleName);
             return `${originalName}.ts`;
         });
         consola.info(`Found ${lambdaFiles.length} built lambda(s)`);
         // Generate manifest
         consola.start("Generating route manifest...");
         try {
-            const manifest = await generateManifest(lambdaFiles, outputDir, config.openapi.enabled, apiName);
+            const manifest = await generateManifest(lambdaFiles, outputDir, config.openapi.enabled, name);
             // Write JSON manifest
             const manifestPath = join(outputDir, "manifest.json");
             await writeManifest(manifest, manifestPath);

package/dist/cli/commands/init/detect.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Detection utilities for init wizard
+ */
+export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+export interface ProjectInfo {
+    /** Whether the directory is empty (only hidden files allowed) */
+    isEmpty: boolean;
+    /** Detected package manager from lockfile, or null */
+    packageManager: PackageManager | null;
+    /** Name from package.json, or null */
+    packageName: string | null;
+    /** Whether elysian.config.ts exists */
+    hasElysianConfig: boolean;
+    /** Whether terraform/ directory exists */
+    hasTerraformDir: boolean;
+    /** Existing terraform files */
+    terraformFiles: {
+        providers: boolean;
+        variables: boolean;
+        main: boolean;
+        outputs: boolean;
+    };
+    /** Whether src/lambdas/ exists */
+    hasLambdasDir: boolean;
+    /** Whether there are any .ts files in src/lambdas/ */
+    hasLambdaFiles: boolean;
+    /** Directory name (for default name) */
+    directoryName: string;
+}
+/**
+ * Gather all project information for the init wizard
+ */
+export declare function detectProject(cwd: string): Promise<ProjectInfo>;

package/dist/cli/commands/init/detect.js

@@ -0,0 +1,98 @@
+/**
+ * Detection utilities for init wizard
+ */
+import { existsSync, readdirSync } from "fs";
+import { join, basename } from "path";
+/**
+ * Check if a directory is empty (ignoring hidden files like .git)
+ */
+function isDirectoryEmpty(cwd) {
+    try {
+        const files = readdirSync(cwd);
+        // Filter out hidden files (starting with .)
+        const visibleFiles = files.filter((f) => !f.startsWith("."));
+        return visibleFiles.length === 0;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Detect package manager from lockfiles
+ */
+function detectPackageManager(cwd) {
+    if (existsSync(join(cwd, "bun.lock")) || existsSync(join(cwd, "bun.lockb"))) {
+        return "bun";
+    }
+    if (existsSync(join(cwd, "pnpm-lock.yaml"))) {
+        return "pnpm";
+    }
+    if (existsSync(join(cwd, "yarn.lock"))) {
+        return "yarn";
+    }
+    if (existsSync(join(cwd, "package-lock.json"))) {
+        return "npm";
+    }
+    return null;
+}
+/**
+ * Read package name from package.json
+ */
+async function readPackageName(cwd) {
+    const packagePath = join(cwd, "package.json");
+    if (!existsSync(packagePath)) {
+        return null;
+    }
+    try {
+        const content = await Bun.file(packagePath).json();
+        return content.name || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check which terraform files exist
+ */
+function checkTerraformFiles(cwd) {
+    const tfDir = join(cwd, "terraform");
+    return {
+        providers: existsSync(join(tfDir, "providers.tf")),
+        variables: existsSync(join(tfDir, "variables.tf")),
+        main: existsSync(join(tfDir, "main.tf")),
+        outputs: existsSync(join(tfDir, "outputs.tf")),
+    };
+}
+/**
+ * Check if there are any .ts files in the lambdas directory
+ */
+function hasLambdaFiles(cwd) {
+    const lambdasDir = join(cwd, "src/lambdas");
+    if (!existsSync(lambdasDir)) {
+        return false;
+    }
+    try {
+        const files = readdirSync(lambdasDir);
+        return files.some((f) => f.endsWith(".ts"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Gather all project information for the init wizard
+ */
+export async function detectProject(cwd) {
+    const packageName = await readPackageName(cwd);
+    return {
+        isEmpty: isDirectoryEmpty(cwd),
+        packageManager: detectPackageManager(cwd),
+        packageName,
+        hasElysianConfig: existsSync(join(cwd, "elysian.config.ts")),
+        hasTerraformDir: existsSync(join(cwd, "terraform")),
+        terraformFiles: checkTerraformFiles(cwd),
+        hasLambdasDir: existsSync(join(cwd, "src/lambdas")),
+        hasLambdaFiles: hasLambdaFiles(cwd),
+        directoryName: basename(cwd),
+    };
+}

package/dist/cli/commands/init/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Init module exports
+ */
+export { detectProject, type ProjectInfo, type PackageManager } from "./detect";
+export { promptTargetDirectory, runFreshProjectWizard, runExistingProjectWizard, type WizardAnswers, } from "./prompts";
+export { scaffoldProject, installDependencies, printResults, type ScaffoldResult, } from "./scaffold";

package/dist/cli/commands/init/index.js

@@ -0,0 +1,6 @@
+/**
+ * Init module exports
+ */
+export { detectProject } from "./detect";
+export { promptTargetDirectory, runFreshProjectWizard, runExistingProjectWizard, } from "./prompts";
+export { scaffoldProject, installDependencies, printResults, } from "./scaffold";

package/dist/cli/commands/init/prompts.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Wizard prompts using consola.prompt
+ */
+import type { PackageManager } from "./detect";
+export interface WizardAnswers {
+    targetDir: string;
+    name: string;
+    packageManager: PackageManager;
+    installDeps: boolean;
+}
+/**
+ * Run the initial wizard to get the target directory
+ * Returns the target directory path, or null if cancelled
+ */
+export declare function promptTargetDirectory(currentDirName: string): Promise<string | null>;
+/**
+ * Run wizard for a fresh (empty) project
+ */
+export declare function runFreshProjectWizard(apiName: string): Promise<Omit<WizardAnswers, "targetDir"> | null>;
+/**
+ * Run wizard for an existing project
+ */
+export declare function runExistingProjectWizard(apiName: string, detectedPackageManager: PackageManager | null): Promise<Omit<WizardAnswers, "targetDir"> | null>;

package/dist/cli/commands/init/prompts.js

@@ -0,0 +1,95 @@
+/**
+ * Wizard prompts using consola.prompt
+ */
+import consola from "consola";
+const CANCEL_SYMBOL = Symbol.for("cancel");
+/**
+ * Check if user cancelled the prompt
+ */
+function isCancelled(value) {
+    return value === CANCEL_SYMBOL;
+}
+/**
+ * Run the initial wizard to get the target directory
+ * Returns the target directory path, or null if cancelled
+ */
+export async function promptTargetDirectory(currentDirName) {
+    console.log("");
+    const targetDir = await consola.prompt("Where would you like to create your project?", {
+        type: "text",
+        default: ".",
+        placeholder: ". (current directory)",
+        cancel: "symbol",
+    });
+    if (isCancelled(targetDir)) {
+        return null;
+    }
+    return targetDir;
+}
+/**
+ * Run wizard for a fresh (empty) project
+ */
+export async function runFreshProjectWizard(apiName) {
+    consola.info(`Creating new elysian project: ${apiName}\n`);
+    // Prompt for package manager
+    const packageManager = await consola.prompt("Package manager:", {
+        type: "select",
+        options: [
+            { value: "bun", label: "bun", hint: "recommended" },
+            { value: "npm", label: "npm" },
+            { value: "pnpm", label: "pnpm" },
+            { value: "yarn", label: "yarn" },
+        ],
+        cancel: "symbol",
+    });
+    if (isCancelled(packageManager)) {
+        return null;
+    }
+    return {
+        name: apiName,
+        packageManager: packageManager,
+        installDeps: true, // Always install for fresh projects
+    };
+}
+/**
+ * Run wizard for an existing project
+ */
+export async function runExistingProjectWizard(apiName, detectedPackageManager) {
+    consola.info(`Adding elysian to: ${apiName}\n`);
+    // Use detected package manager or prompt
+    let packageManager;
+    if (detectedPackageManager) {
+        packageManager = detectedPackageManager;
+        consola.info(`Detected package manager: ${packageManager}`);
+    }
+    else {
+        const selected = await consola.prompt("Package manager:", {
+            type: "select",
+            options: [
+                { value: "bun", label: "bun", hint: "recommended" },
+                { value: "npm", label: "npm" },
+                { value: "pnpm", label: "pnpm" },
+                { value: "yarn", label: "yarn" },
+            ],
+            cancel: "symbol",
+        });
+        if (isCancelled(selected)) {
+            return null;
+        }
+        packageManager = selected;
+    }
+    // Prompt whether to install dependencies
+    const installDeps = await consola.prompt("Install dependencies?", {
+        type: "confirm",
+        initial: true,
+        cancel: "symbol",
+    });
+    if (isCancelled(installDeps)) {
+        return null;
+    }
+    return {
+        name: apiName,
+        packageManager,
+        installDeps: installDeps,
+    };
+}