@ketrics/ketrics-cli 0.1.0 → 0.2.1

package/README.md

@@ -1,326 +1,746 @@
 # Ketrics CLI
 
-CLI tool for deploying applications to the Ketrics platform.
+Command-line interface for scaffolding, building, and deploying applications to the Ketrics platform.
 
-## Installation
+## 1. Overview
 
-```bash
-# Install globally
-npm install -g ketrics-cli
+### Purpose
 
-# Or use npx
-npx ketrics-cli deploy
+The Ketrics CLI (`@ketrics/ketrics-cli`) is a developer tool that streamlines the full lifecycle of Ketrics tenant applications—from project scaffolding to production deployment. It abstracts the complexity of packaging frontend and backend code into deployment bundles and handles authentication with the Ketrics Tenant API API.
 
-# Or link locally for development
-cd ketrics-cli
-npm install
-npm run build
-npm link
+### Architecture Position
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                     Developer Workstation                        │
+│  ┌─────────────┐     ┌────────────────┐     ┌────────────────┐  │
+│  │ Application │────▶│  Ketrics CLI   │────▶│ Tenant API  │  │
+│  │   Source    │     │ (build & zip)  │     │     API        │  │
+│  └─────────────┘     └────────────────┘     └────────────────┘  │
+└──────────────────────────────────────────────────────────────────┘
+                                │
+                                │ Presigned URL
+                                ▼
+                         ┌──────────────┐
+                         │     S3       │
+                         │ (code-bundle)│
+                         └──────────────┘
+                                │
+                                │ S3 Event Trigger
+                                ▼
+                         ┌──────────────┐     ┌──────────────┐
+                         │  Deployment  │────▶│     EFS      │
+                         │   Lambda     │     │  (extracted) │
+                         └──────────────┘     └──────────────┘
+                                                     │
+                                                     ▼
+                                              ┌──────────────┐
+                                              │  Data Plane  │
+                                              │   (runtime)  │
+                                              └──────────────┘
 ```
 
-## Quick Start
+The CLI sits at the beginning of the deployment pipeline:
 
-1. **Create a new application from template:**
+1. Developers write frontend (React) and backend (TypeScript handlers) code
+2. CLI builds both, packages them into a single ZIP archive
+3. CLI uploads the ZIP to S3 via a presigned URL obtained from Tenant API API
+4. Downstream systems (Deployment Lambda) extract the bundle to EFS for Data Plane execution
 
-   ```bash
-   ketrics create my-app
-   ```
+### Key Responsibilities
 
-   This will:
-   - Create a new folder `my-app/`
-   - Let you choose a template interactively
-   - Copy template files to the folder
-   - Update app name in configuration files
+- **Project scaffolding**: Generate new applications from bundled templates
+- **Configuration validation**: Validate `ketrics.config.json` and `.env` files using Zod schemas
+- **Build orchestration**: Execute `npm run build` for both frontend and backend
+- **Deployment packaging**: Create ZIP archives with frontend/backend in a flat structure
+- **API communication**: Authenticate with Tenant API and obtain presigned upload URLs
+- **S3 upload**: Push deployment bundles to the platform
+- **Runtime testing**: Execute API requests against deployed applications via `ketrics run`
 
-2. **Install dependencies:**
+### Boundaries
 
-   ```bash
-   cd my-app
-   cd frontend && npm install
-   cd ../backend && npm install
-   ```
+The CLI does **not**:
 
-3. **Configure credentials** (copy `.env.example` to `.env`):
+- Execute application code (that's the Data Plane's role)
+- Manage infrastructure (handled by Terraform)
+- Handle tenant/user management (Tenant API API's domain)
+- Extract bundles to EFS (Deployment Lambda's responsibility)
 
-   ```bash
-   KETRICS_TOKEN=ktd_your-token-id_your-secret-key
-   KETRICS_API_URL=https://api.ketrics.cl/api/v1
-   KETRICS_TENANT_ID=your-tenant-uuid
-   KETRICS_APPLICATION_ID=your-application-uuid
-   ```
+---
 
-4. **Deploy:**
-   ```bash
-   ketrics deploy
-   ```
+## 2. Business Logic
 
-   The CLI will:
-   - Build frontend (npm run build)
-   - Build backend (npm run build)
-   - Create ZIP with both builds
-   - Upload to Ketrics platform
+### Problem Statement
 
-## Commands
+Developers building Ketrics applications need a consistent, reliable way to:
 
-### `ketrics create <app-name>`
+1. Bootstrap new projects with correct structure and configuration
+2. Build and package both frontend and backend code
+3. Deploy code bundles to the platform with proper authentication
+4. Test deployed functions without building custom HTTP clients
 
-Create a new Ketrics application from a template.
+### Core Workflows
+
+#### Scaffold Workflow (`ketrics create`)
 
-```bash
-ketrics create my-app                      # Interactive template selection
-ketrics create my-app --template <name>    # Use specific template
+```
+1. Validate app name (alphanumeric, starts with letter)
+2. Check destination directory doesn't exist
+3. List available templates from bundled /templates directory
+4. Interactive template selection (or use --template flag)
+5. Copy template files to new directory
+6. Update app name in ketrics.config.json, frontend/package.json, backend/package.json
 ```
 
-**What it does:**
-1. Creates a folder with the provided app name (fails if folder exists)
-2. Prompts for template selection (or uses `--template` flag)
-3. Copies template files to the new folder
-4. Updates app name in:
-   - `ketrics.config.json`
-   - `frontend/package.json`
-   - `backend/package.json`
+#### Build Workflow (`ketrics build`)
 
-### `ketrics build`
+```
+1. Validate frontend/ directory exists with node_modules
+2. Validate backend/ directory exists with node_modules
+3. Run `npm run build` in frontend/ (expects dist/ output)
+4. Run `npm run build` in backend/ (expects dist/ output)
+5. Verify both dist/ directories were created
+```
 
-Build frontend and backend without deploying.
+#### Deploy Workflow (`ketrics deploy`)
 
-```bash
-ketrics build
+```
+1. Load .env file and validate required KETRICS_* variables
+2. Validate deployment token format (must start with "ktd_")
+3. Execute full build workflow (frontend + backend)
+4. Create ZIP archive:
+   - frontend/ folder containing frontend/dist/* contents
+   - backend/ folder containing backend/dist/* contents
+5. Call Tenant API API: POST /tenants/{tenantId}/applications/{appId}/deploy
+6. Receive presigned S3 URL with deploymentId
+7. PUT ZIP buffer to presigned URL
+8. Display success with deploymentId, file count, size, duration
 ```
 
-**What it does:**
-1. Runs `npm run build` in `frontend/`
-2. Runs `npm run build` in `backend/`
-3. Outputs the location of built files
+#### Validate Workflow (`ketrics validate`)
 
-### `ketrics deploy`
+```
+1. Check ketrics.config.json exists and is valid JSON
+2. Validate against ketricsConfigSchema (Zod)
+3. Check .env file exists
+4. Validate KETRICS_* variables against envConfigSchema
+5. Report errors and warnings (e.g., token format, empty exclude patterns)
+```
 
-Build and deploy frontend/backend to Ketrics.
+#### Run Workflow (`ketrics run <json-file>`)
 
-```bash
-ketrics deploy                    # Build and deploy
-ketrics deploy --env <path>       # Use specific .env file
-ketrics deploy --dry-run          # Build and show what would be deployed
 ```
+1. Load .env file (requires KETRICS_AUTH_TOKEN and KETRICS_RUNTIME_URL)
+2. Parse JSON file against runFileSchema
+3. Interpolate template variables: {{tenantId}}, {{applicationId}}, {{token}}
+4. Construct full URL: KETRICS_RUNTIME_URL + interpolated endpoint
+5. Execute HTTP request (GET/POST/PUT/DELETE/PATCH)
+6. Display formatted response with status and body
+```
+
+### Business Rules
+
+| Rule                                       | Implementation                                  |
+| ------------------------------------------ | ----------------------------------------------- |
+| App names must be valid identifiers        | Regex: `^[a-zA-Z][a-zA-Z0-9_-]*$`               |
+| Deployment tokens must have correct prefix | Token must start with `ktd_`                    |
+| Tenant/Application IDs must be UUIDs       | Zod `.uuid()` validation                        |
+| API URL must be valid HTTPS URL            | Zod `.url()` validation                         |
+| Both frontend and backend must build       | Both `dist/` directories must exist after build |
+| Templates must have ketrics.config.json    | Templates without config are skipped            |
+
+### Input/Output Expectations
+
+**Deploy Input:**
+
+- `.env` file with `KETRICS_TOKEN`, `KETRICS_API_URL`, `KETRICS_TENANT_ID`, `KETRICS_APPLICATION_ID`
+- `frontend/` directory with `package.json` and `node_modules`
+- `backend/` directory with `package.json` and `node_modules`
+
+**Deploy Output:**
+
+- ZIP file uploaded to S3 with structure:
+  ```
+  bundle.zip
+  ├── frontend/
+  │   ├── index.html
+  │   └── assets/
+  │       ├── index-*.js
+  │       └── index-*.css
+  └── backend/
+      ├── index.js
+      └── index.d.ts
+  ```
+
+### Edge Cases Handled
+
+- **Destination folder exists**: `ketrics create` fails early with clear error
+- **node_modules missing**: Build command detects and prompts user to run `npm install`
+- **Empty dist directories**: Error thrown if no files found after build
+- **Network failures**: Axios timeout (30s API, 5min upload) with specific error messages
+- **Expired presigned URL**: Clear error message on 403/400 from S3
+- **Invalid JSON in config files**: Parse errors with file path and position
+
+---
+
+## 3. Technical Details
+
+### Technology Stack
+
+| Component             | Technology        | Version  |
+| --------------------- | ----------------- | -------- |
+| Runtime               | Node.js           | >=24.0.0 |
+| Language              | TypeScript        | ^5.3.3   |
+| CLI Framework         | Commander.js      | ^12.0.0  |
+| HTTP Client           | Axios             | ^1.6.0   |
+| Schema Validation     | Zod               | ^3.22.4  |
+| ZIP Creation          | Archiver          | ^6.0.1   |
+| File Patterns         | glob              | ^10.3.0  |
+| Interactive Prompts   | @inquirer/prompts | ^7.10.1  |
+| Console Styling       | Chalk             | ^4.1.2   |
+| Loading Spinners      | ora               | ^5.4.1   |
+| Environment Variables | dotenv            | ^16.3.1  |
+
+### File Structure
 
-**What it does:**
-1. Validates `.env` configuration
-2. Builds `frontend/` (runs `npm run build`)
-3. Builds `backend/` (runs `npm run build`)
-4. Creates ZIP with flat structure:
-   - `frontend/` - contents of `frontend/dist/`
-   - `backend/` - contents of `backend/dist/`
-5. Uploads to S3 via presigned URL
+```
+ketrics-cli/
+├── bin/
+│   └── ketrics.ts              # CLI entry point (shebang executable)
+├── src/
+│   ├── cli.ts                  # Commander program setup, command registration
+│   ├── index.ts                # Programmatic exports for library usage
+│   ├── commands/
+│   │   ├── create.ts           # ketrics create - project scaffolding
+│   │   ├── build.ts            # ketrics build - compile without deploy
+│   │   ├── deploy.ts           # ketrics deploy - build + package + upload
+│   │   ├── validate.ts         # ketrics validate - config validation
+│   │   └── run.ts              # ketrics run - execute API requests
+│   ├── services/
+│   │   ├── api-client.ts       # HTTP client for Tenant API API
+│   │   ├── build-service.ts    # npm build execution and validation
+│   │   ├── config-service.ts   # Load/validate ketrics.config.json and .env
+│   │   ├── template-service.ts # Template discovery, copying, name updates
+│   │   ├── upload-service.ts   # S3 presigned URL upload
+│   │   └── zip-service.ts      # ZIP archive creation from dist directories
+│   ├── types/
+│   │   └── index.ts            # Zod schemas and TypeScript interfaces
+│   └── utils/
+│       ├── logger.ts           # Colored console output (chalk wrapper)
+│       └── spinner.ts          # Loading spinner wrapper (ora)
+├── templates/
+│   └── ketrics-app-v1/         # Bundled project template
+│       ├── ketrics.config.json
+│       ├── frontend/           # React + Vite starter
+│       ├── backend/            # TypeScript handlers starter
+│       └── tests/              # Sample run files for ketrics run
+├── package.json
+└── tsconfig.json
+```
 
-### `ketrics validate`
+### Key Functions and Classes
 
-Validate configuration and `.env` files.
+#### `src/cli.ts`
 
-```bash
-ketrics validate                  # Validate default files
-ketrics validate --env <path>     # Validate specific .env
+```typescript
+export function createCLI(): Command;
 ```
 
-### `ketrics --version`
+Creates the Commander program with all commands registered. Each command is defined with options, descriptions, and action handlers.
 
-Show CLI version.
+#### `src/services/config-service.ts`
 
-### `ketrics --help`
+```typescript
+export function loadKetricsConfig(configPath?: string): KetricsConfig;
+```
 
-Show help information.
+Loads and validates `ketrics.config.json` against the Zod schema. Throws descriptive errors for missing files or validation failures.
 
-## Project Structure
+```typescript
+export function loadEnvConfig(envPath?: string): EnvConfig;
+```
 
-After running `ketrics create my-app`, your project will have:
+Loads `.env` file using dotenv, extracts `KETRICS_*` variables, and validates against schema.
 
+```typescript
+export function validateConfig(configPath?: string, envPath?: string): ValidationResult;
 ```
-my-app/
-├── .env.example        # Environment variables template
-├── .gitignore          # Git ignore file
-├── ketrics.config.json # Application configuration
-├── README.md           # Documentation
-├── frontend/           # React + TypeScript + Vite
-│   ├── src/
-│   ├── package.json
-│   └── vite.config.ts
-└── backend/            # TypeScript handlers
-    ├── src/
-    ├── package.json
-    └── tsconfig.json
+
+Non-throwing validation that returns `{ valid: boolean, errors: string[], warnings: string[] }`.
+
+#### `src/services/build-service.ts`
+
+```typescript
+export function buildAll(projectDir: string): BuildResult;
 ```
 
-## Configuration
+Orchestrates building both frontend and backend. Returns paths to both `dist/` directories. Executes `npm run build` via `child_process.execSync` with `stdio: 'inherit'` to show build output.
 
-### `ketrics.config.json`
+```typescript
+export function validateBuildDirectory(dir: string, name: string): BuildValidation;
+```
+
+Checks that a directory exists, has `node_modules`, and has `package.json`.
 
-| Field         | Type     | Required | Description                              |
-| ------------- | -------- | -------- | ---------------------------------------- |
-| `name`        | string   | Yes      | Application name                         |
-| `version`     | string   | Yes      | Semver version (e.g., "1.0.0")           |
-| `description` | string   | No       | Application description                  |
-| `runtime`     | string   | Yes      | Runtime: "nodejs18", "nodejs20", "static"|
-| `actions`     | string[] | Yes      | List of exported backend actions         |
-| `entry`       | string   | Yes      | Backend entry point file                 |
-| `include`     | string[] | Yes      | Glob patterns for files to include       |
-| `exclude`     | string[] | No       | Glob patterns for files to exclude       |
+#### `src/services/zip-service.ts`
 
-### Environment Variables
+```typescript
+export async function createDeploymentZipBundle(
+  frontendDistPath: string,
+  backendDistPath: string,
+): Promise<{ buffer: Buffer; files: FileInfo[]; totalSourceSize: number; zipSize: number }>;
+```
 
-| Variable                 | Required | Description                      |
-| ------------------------ | -------- | -------------------------------- |
-| `KETRICS_TOKEN`          | Yes      | Deployment token from dashboard  |
-| `KETRICS_API_URL`        | Yes      | Ketrics API URL                  |
-| `KETRICS_TENANT_ID`      | Yes      | Your tenant UUID                 |
-| `KETRICS_APPLICATION_ID` | Yes      | Application UUID                 |
+Creates a ZIP buffer from frontend and backend dist directories. Uses archiver with `zlib: { level: 9 }` for maximum compression. Files are organized under `frontend/` and `backend/` prefixes.
 
-## Deployment Flow
+#### `src/services/api-client.ts`
 
-1. Load `.env` file and validate Ketrics variables
-2. Build frontend using `npm run build`
-3. Build backend using `npm run build`
-4. Create ZIP with `frontend/` and `backend/` folders
-5. Request presigned URL from Ketrics API
-6. Upload ZIP to S3 via presigned URL
-7. Display deployment success with deployment ID
+```typescript
+export async function initiateDeploy(envConfig: EnvConfig): Promise<DeployResponse>;
+```
 
-## Example Output
+Calls `POST /tenants/{tenantId}/applications/{appId}/deploy` with Bearer token authentication. Returns presigned URL, deploymentId, and S3 key. Handles 401/403/404 with user-friendly error messages.
 
-### Create Command
+#### `src/services/upload-service.ts`
 
+```typescript
+export async function uploadToS3(presignedUrl: string, zipBuffer: Buffer): Promise<void>;
 ```
-$ ketrics create my-app
 
-  Available Templates
+Uploads ZIP buffer to S3 via presigned URL using PUT with `Content-Type: application/zip`. 5-minute timeout for large uploads.
 
-  1. ketrics-app-v1
-    My Ketrics application
+#### `src/services/template-service.ts`
 
-Select a template (enter number): 1
+```typescript
+export function getAvailableTemplates(): TemplateInfo[];
+```
 
-Creating 'my-app' with template: ketrics-app-v1
+Scans the `templates/` directory for subdirectories containing `ketrics.config.json`.
 
-Files to create:
-    my-app/.env.example
-    my-app/.gitignore
-    my-app/README.md
-    my-app/ketrics.config.json
-    my-app/backend/package.json
-    my-app/backend/src/index.ts
-    ...
+```typescript
+export function copyTemplate(template: TemplateInfo, destDir: string): void;
+```
 
-✔ Created 'my-app' successfully!
+Recursively copies template files to destination directory.
 
-Next steps:
-  1. cd my-app
-  2. cd frontend && npm install
-  3. cd ../backend && npm install
-  4. Copy .env.example to .env and add your credentials
-  5. Run 'ketrics deploy' to deploy your application
+```typescript
+export function updateAppName(projectDir: string, appName: string): void;
 ```
 
-### Build Command
+Updates the `name` field in `ketrics.config.json`, `frontend/package.json`, and `backend/package.json`.
+
+### Configuration Options
 
+#### `ketrics.config.json` Schema
+
+```typescript
+const ketricsConfigSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/), // semver
+  description: z.string().optional(),
+  runtime: z.enum(["nodejs18", "nodejs20", "static"]).default("nodejs18"),
+  actions: z.array(z.string()).min(1),
+  entry: z.string().min(1),
+  include: z.array(z.string()).min(1),
+  exclude: z.array(z.string()).default([]),
+});
 ```
-$ ketrics build
 
-  Ketrics CLI v1.0.0 - Build
+#### Environment Variables
 
-ℹ Building frontend and backend...
+| Variable                 | Required  | Description                                                   |
+| ------------------------ | --------- | ------------------------------------------------------------- |
+| `KETRICS_TOKEN`          | Yes       | Deployment token (format: `ktd_{id}_{secret}`)                |
+| `KETRICS_API_URL`        | Yes       | Tenant API API URL (e.g., `https://api.ketrics.io/api/v1`) |
+| `KETRICS_TENANT_ID`      | Yes       | Tenant UUID                                                   |
+| `KETRICS_APPLICATION_ID` | Yes       | Application UUID                                              |
+| `KETRICS_AUTH_TOKEN`     | For `run` | User auth token for runtime API calls                         |
+| `KETRICS_RUNTIME_URL`    | For `run` | Data Plane runtime URL                                        |
 
-> frontend build output...
-> backend build output...
+### External Integrations
 
-✔ Build completed successfully!
+1. **Tenant API API**:
+   - Endpoint: `POST /tenants/{tenantId}/applications/{applicationId}/deploy`
+   - Auth: Bearer token (`KETRICS_TOKEN`)
+   - Response: Presigned S3 URL, deployment ID
 
-Frontend dist: /path/to/frontend/dist
-Backend dist:  /path/to/backend/dist
-```
+2. **AWS S3**:
+   - Upload method: HTTP PUT to presigned URL
+   - Content-Type: `application/zip`
+   - Max upload timeout: 5 minutes
 
-### Deploy Command
+3. **Data Plane API** (via `ketrics run`):
+   - Endpoint: User-defined in JSON config files
+   - Auth: Bearer token (`KETRICS_AUTH_TOKEN`)
 
-```
-$ ketrics deploy
+---
 
-  Ketrics CLI v1.0.0
+## 4. Data Flow
 
-  ✔ Loaded environment configuration
-  ✔ Validated deployment token
+### Create Command Flow
 
-  Building frontend and backend...
+```
+User Input (app name)
+        │
+        ▼
+┌───────────────────┐
+│  Validate Name    │ ── Invalid ──▶ Exit with error
+└───────────────────┘
+        │ Valid
+        ▼
+┌───────────────────┐
+│ Check Dest Dir    │ ── Exists ──▶ Exit with error
+└───────────────────┘
+        │ OK
+        ▼
+┌───────────────────┐
+│ List Templates    │ ◀── Scan templates/ directory
+└───────────────────┘
+        │
+        ▼
+┌───────────────────┐
+│ Select Template   │ ◀── Interactive prompt or --template flag
+└───────────────────┘
+        │
+        ▼
+┌───────────────────┐
+│ Copy Files        │ ── Recursive copy to dest dir
+└───────────────────┘
+        │
+        ▼
+┌───────────────────┐
+│ Update App Name   │ ── Modify JSON files in-place
+└───────────────────┘
+        │
+        ▼
+Success message with next steps
+```
 
-  > frontend build output...
-  > backend build output...
+### Deploy Command Flow
 
-  ✔ Frontend and backend built successfully
-  ✔ Created deployment ZIP archive
-  ✔ ZIP archive: 59.9 KB from 5 files
-  ✔ Initiated deployment
-  ✔ Uploaded to S3
+```
+.env file
+    │
+    ▼
+┌───────────────────┐
+│  Load & Validate  │ ── Invalid ──▶ Exit with error
+│    Environment    │
+└───────────────────┘
+    │
+    ▼
+┌───────────────────┐
+│ Validate Token    │ ── Not ktd_ ──▶ Exit with error
+└───────────────────┘
+    │
+    ▼
+┌───────────────────────────────────────────┐
+│          Build Phase                       │
+│  ┌─────────────────┐  ┌─────────────────┐ │
+│  │ npm run build   │  │ npm run build   │ │
+│  │   (frontend)    │  │   (backend)     │ │
+│  └────────┬────────┘  └────────┬────────┘ │
+│           │                    │          │
+│           ▼                    ▼          │
+│    frontend/dist/        backend/dist/    │
+└───────────────────────────────────────────┘
+    │
+    ▼
+┌───────────────────┐
+│  Create ZIP       │
+│  - frontend/*     │
+│  - backend/*      │
+│  (level 9 zlib)   │
+└───────────────────┘
+    │ Buffer
+    ▼
+┌───────────────────┐                    ┌───────────────────┐
+│ Tenant API API │ ──────────────────▶│  DeployResponse   │
+│ POST .../deploy   │                    │  - uploadUrl      │
+│ Bearer ktd_...    │                    │  - deploymentId   │
+└───────────────────┘                    │  - s3Key          │
+                                         └───────────────────┘
+    │ uploadUrl
+    ▼
+┌───────────────────┐
+│  PUT to S3        │
+│  presigned URL    │
+│  Content-Type:    │
+│  application/zip  │
+└───────────────────┘
+    │
+    ▼
+Success box with deploymentId
+```
 
-  Deployment successful!
+### Run Command Flow
 
-  Deployment ID: 550e8400-e29b-41d4-a716-446655440002
-  Files:         5
-  Size:          59.9 KB
-  Duration:      3.2s
+```
+JSON config file (e.g., test.greet.json)
+    │
+    │  {
+    │    "endpoint": "/tenants/{{tenantId}}/apps/{{appId}}/functions/greet",
+    │    "method": "POST",
+    │    "headers": { "Authorization": "Bearer {{token}}" },
+    │    "body": { "name": "World" }
+    │  }
+    │
+    ▼
+┌───────────────────┐
+│ Load .env         │
+│ (KETRICS_AUTH_    │
+│  TOKEN required)  │
+└───────────────────┘
+    │
+    ▼
+┌───────────────────┐
+│ Parse & Validate  │ ── Zod runFileSchema
+│    JSON File      │
+└───────────────────┘
+    │
+    ▼
+┌───────────────────┐
+│ Interpolate Vars  │ ── Replace {{tenantId}}, {{applicationId}}, {{token}}
+└───────────────────┘
+    │
+    ▼
+┌───────────────────┐
+│ Execute Request   │ ── axios({ method, url, headers, data })
+│ KETRICS_RUNTIME_  │
+│ URL + endpoint    │
+└───────────────────┘
+    │
+    ▼
+Formatted response (status + JSON body)
+```
 
-  Your deployment is being processed by Ketrics.
+---
+
+## 5. Error Handling
+
+### Error Scenarios
+
+| Scenario               | Detection                        | User Message                                                                                    |
+| ---------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Missing .env file      | `fs.existsSync()` check          | "Environment file not found: {path}"                                                            |
+| Invalid JSON in config | JSON.parse throws                | "Invalid JSON in configuration file: {path}"                                                    |
+| Zod validation failure | `safeParse().success === false`  | "Invalid configuration:\n - {field}: {message}"                                                 |
+| Invalid token format   | String prefix check              | "Invalid token format. Token should start with 'ktd\_'"                                         |
+| Missing node_modules   | Directory check                  | "Missing node_modules in {dir}/. Run 'cd {dir} && npm install' first."                          |
+| Build failure          | execSync throws                  | "{name} build failed. Check the output above for errors."                                       |
+| No dist directory      | Post-build directory check       | "{name} build did not produce dist/ directory"                                                  |
+| API 401                | HTTP status check                | "Authentication failed: Invalid or expired deployment token."                                   |
+| API 403                | HTTP status check                | "Authorization failed: Token does not have access to this application."                         |
+| API 404                | HTTP status check                | "Application not found. Please verify KETRICS_APPLICATION_ID."                                  |
+| Network error          | axios.isAxiosError + no response | "Network error: Could not connect to {url}"                                                     |
+| S3 upload 403          | HTTP status check                | "Upload failed: Access denied. The presigned URL may have expired or been used."                |
+| S3 upload 413          | HTTP status check                | "Upload failed: File too large. Maximum upload size exceeded."                                  |
+| Upload timeout         | axios timeout                    | "Upload failed: Network error. Please check your internet connection."                          |
+| Folder already exists  | `fs.existsSync()`                | "Folder '{name}' already exists."                                                               |
+| Invalid app name       | Regex test                       | "App name must start with a letter and contain only letters, numbers, hyphens, and underscores" |
+
+### Retry Logic
+
+The CLI does **not** implement automatic retry for API calls. Network failures result in immediate error and process exit. This is intentional—deployments are explicit actions where the developer should understand and resolve any connectivity issues before retrying.
+
+### Logging Approach
+
+All user-facing output goes through `src/utils/logger.ts`:
+
+```typescript
+logger.info(message)    // Blue ℹ prefix
+logger.success(message) // Green ✔ prefix
+logger.warn(message)    // Yellow ⚠ prefix
+logger.error(message)   // Red ✖ prefix
+logger.keyValue(k, v)   // Formatted key: value pairs
+logger.file(path, size) // Cyan file path with optional size
+logger.box(title, [...])// Green success box with details
 ```
 
-### Dry Run
+Long-running operations use spinners (`src/utils/spinner.ts`):
 
+```typescript
+await withSpinner(
+  "Loading environment configuration", // Shown during operation
+  async () => loadEnvConfig(options.env),
+  "Loaded environment configuration", // Shown on success
+);
 ```
-$ ketrics deploy --dry-run
 
-  Ketrics CLI v1.0.0
+Build output is passed through to the terminal via `stdio: 'inherit'` in `execSync`, so developers see native npm/Vite/TypeScript output.
 
-  ✔ Loaded environment configuration
-  ✔ Validated deployment token
+---
 
-  Building frontend and backend...
-  ✔ Frontend and backend built successfully
+## 6. Usage
 
-  Dry run - no files were uploaded
+### Installation
 
-  Files to deploy:
-    frontend/
-      assets/index-xxx.js (192.8 KB)
-      assets/index-xxx.css (1.4 KB)
-      index.html (471 B)
+```bash
+# Global installation
+npm install -g @ketrics/ketrics-cli
 
-    backend/
-      index.d.ts (1.2 KB)
-      index.js (3.4 KB)
+# Or run directly with npx
+npx @ketrics/ketrics-cli deploy
 
-  Total files: 5
-  Frontend files: 3
-  Backend files: 2
-  Source size: 199.3 KB
-  ZIP size: 59.9 KB
+# Development installation (from source)
+cd ketrics-cli
+npm install
+npm run build
+npm link
 ```
 
-## Error Handling
+### Commands
 
-### Missing node_modules
+#### Create New Application
 
+```bash
+# Interactive template selection
+ketrics create my-app
+
+# Use specific template
+ketrics create my-app --template ketrics-app-v1
 ```
-✖ Missing node_modules in frontend/. Run 'cd frontend && npm install' first.
+
+#### Build Without Deploying
+
+```bash
+ketrics build
 ```
 
-### Folder already exists
+#### Deploy to Platform
+
+```bash
+# Standard deployment
+ketrics deploy
 
+# Use specific .env file
+ketrics deploy --env /path/to/.env
+
+# Preview what would be deployed (no upload)
+ketrics deploy --dry-run
 ```
-$ ketrics create my-app
-✖ Folder 'my-app' already exists.
+
+#### Validate Configuration
+
+```bash
+# Validate default files
+ketrics validate
+
+# Validate specific files
+ketrics validate --config ./custom.config.json --env ./custom.env
 ```
 
-### Invalid app name
+#### Execute API Request
+
+```bash
+# Run test request from JSON file
+ketrics run tests/test.greet.json
 
+# With custom .env and verbose output
+ketrics run tests/test.echo.json --env .env.local --verbose
 ```
-$ ketrics create 123-invalid
-✖ App name must start with a letter and contain only letters, numbers, hyphens, and underscores
+
+### Example Run File
+
+`tests/test.greet.json`:
+
+```json
+{
+  "endpoint": "/tenants/{{tenantId}}/applications/{{applicationId}}/functions/greet",
+  "method": "POST",
+  "headers": {
+    "Authorization": "Bearer {{token}}",
+    "Content-Type": "application/json"
+  },
+  "body": {
+    "name": "World"
+  }
+}
+```
+
+### Development Commands
+
+```bash
+# Build TypeScript to dist/
+npm run build
+
+# Run CLI in development mode (ts-node)
+npm run dev -- create my-app
+npm run dev -- deploy --dry-run
+
+# Clean build artifacts
+npm run clean
 ```
 
-## License
+### Testing Approach
+
+The CLI does not include automated tests in the current implementation. Testing is performed manually:
+
+1. **Unit testing config validation**: Create various `.env` and `ketrics.config.json` files with valid/invalid data, run `ketrics validate`
+2. **Integration testing deployment**:
+   - `ketrics create test-app`
+   - `cd test-app/frontend && npm install && cd ../backend && npm install`
+   - Configure `.env` with real credentials
+   - `ketrics deploy --dry-run` to verify packaging
+   - `ketrics deploy` to test full flow
+3. **Runtime testing**: Use `ketrics run tests/test.*.json` against deployed application
 
-MIT
+### Example Session
+
+```bash
+# Create a new application
+$ ketrics create hello-world
+
+Creating 'hello-world' with template: ketrics-app-v1
+
+Files to create:
+    hello-world/ketrics.config.json
+    hello-world/frontend/package.json
+    hello-world/backend/package.json
+    ...
+
+✔ Created 'hello-world' successfully!
+
+Next steps:
+  1. cd hello-world
+  2. cd frontend && npm install
+  3. cd ../backend && npm install
+  4. Copy .env.example to .env and add your credentials
+  5. Run 'ketrics deploy' to deploy your application
+
+# Install dependencies
+$ cd hello-world
+$ cd frontend && npm install && cd ../backend && npm install
+
+# Configure credentials
+$ cp .env.example .env
+$ vim .env  # Add your KETRICS_TOKEN, etc.
+
+# Deploy
+$ ketrics deploy
+
+Ketrics CLI v1.0.0
+
+✔ Loaded environment configuration
+✔ Validated deployment token
+
+Building frontend and backend...
+
+> hello-world@1.0.0 build
+> vite build
+...
+
+✔ Frontend and backend built successfully
+✔ Created deployment ZIP archive
+✔ ZIP archive: 45.2 KB from 6 files
+✔ Initiated deployment
+✔ Uploaded to S3
+
+  ✅ Deployment successful!
+
+  Deployment ID: 550e8400-e29b-41d4-a716-446655440002
+  Files:         6
+  Size:          45.2 KB
+  Duration:      4.1s
+
+  Your deployment is being processed by Ketrics.
+```

package/dist/src/cli.d.ts

@@ -3,7 +3,7 @@
  *
  * Command-line interface setup using Commander.js.
  */
-import { Command } from 'commander';
+import { Command } from "commander";
 /**
  * Create and configure CLI program
  */

package/dist/src/cli.js

@@ -12,21 +12,21 @@ const build_1 = require("./commands/build");
 const deploy_1 = require("./commands/deploy");
 const validate_1 = require("./commands/validate");
 const run_1 = require("./commands/run");
-const VERSION = '1.0.0';
+const VERSION = "0.1.1";
 /**
  * Create and configure CLI program
  */
 function createCLI() {
     const program = new commander_1.Command();
     program
-        .name('ketrics')
-        .description('CLI tool for deploying applications to Ketrics platform')
-        .version(VERSION, '-v, --version', 'Show CLI version');
+        .name("ketrics")
+        .description("CLI tool for deploying applications to Ketrics platform")
+        .version(VERSION, "-v, --version", "Show CLI version");
     // Create command
     program
-        .command('create <app-name>')
-        .description('Create a new Ketrics application from a template')
-        .option('-t, --template <name>', 'Use specific template (skip interactive selection)')
+        .command("create <app-name>")
+        .description("Create a new Ketrics application from a template")
+        .option("-t, --template <name>", "Use specific template (skip interactive selection)")
         .action(async (appName, options) => {
         await (0, create_1.createCommand)(appName, {
             template: options.template,
@@ -34,17 +34,17 @@ function createCLI() {
     });
     // Build command
     program
-        .command('build')
-        .description('Build frontend and backend without deploying')
+        .command("build")
+        .description("Build frontend and backend without deploying")
         .action(async () => {
         await (0, build_1.buildCommand)();
     });
     // Deploy command
     program
-        .command('deploy')
-        .description('Build and deploy frontend/backend to Ketrics')
-        .option('-e, --env <path>', 'Path to .env file')
-        .option('--dry-run', 'Build and show what would be deployed without uploading')
+        .command("deploy")
+        .description("Build and deploy frontend/backend to Ketrics")
+        .option("-e, --env <path>", "Path to .env file")
+        .option("--dry-run", "Build and show what would be deployed without uploading")
         .action(async (options) => {
         await (0, deploy_1.deployCommand)({
             env: options.env,
@@ -53,19 +53,19 @@ function createCLI() {
     });
     // Validate command
     program
-        .command('validate')
-        .description('Validate configuration and .env files')
-        .option('-c, --config <path>', 'Path to ketrics.config.json')
-        .option('-e, --env <path>', 'Path to .env file')
+        .command("validate")
+        .description("Validate configuration and .env files")
+        .option("-c, --config <path>", "Path to ketrics.config.json")
+        .option("-e, --env <path>", "Path to .env file")
         .action(async (options) => {
         await (0, validate_1.validateCommand)(options.config, options.env);
     });
     // Run command
     program
-        .command('run <json-file>')
-        .description('Execute an API request from a JSON configuration file')
-        .option('-e, --env <path>', 'Path to .env file')
-        .option('-v, --verbose', 'Show detailed request/response information')
+        .command("run <json-file>")
+        .description("Execute an API request from a JSON configuration file")
+        .option("-e, --env <path>", "Path to .env file")
+        .option("-v, --verbose", "Show detailed request/response information")
         .action(async (jsonFile, options) => {
         await (0, run_1.runCommand)(jsonFile, {
             env: options.env,

package/dist/src/services/api-client.d.ts

@@ -1,7 +1,7 @@
 /**
  * API Client Service
  *
- * HTTP client for communicating with Ketrics Control Plane API.
+ * HTTP client for communicating with Ketrics Tenant API.
  */
 import type { EnvConfig, DeployResponse } from "../types";
 /**

package/dist/src/services/api-client.js

@@ -2,7 +2,7 @@
 /**
  * API Client Service
  *
- * HTTP client for communicating with Ketrics Control Plane API.
+ * HTTP client for communicating with Ketrics Tenant API.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ketrics/ketrics-cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI tool for deploying applications to Ketrics platform",
   "main": "dist/index.js",
   "bin": {
@@ -34,11 +34,11 @@
   "devDependencies": {
     "@types/archiver": "^6.0.2",
     "@types/node": "^20.10.0",
-    "ts-node": "^10.9.2",
+    "ts-node": "^1.7.1",
     "typescript": "^5.3.3"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=24.0.0"
   },
   "files": [
     "dist",

package/templates/ketrics-app-v1/.env.example

@@ -5,7 +5,7 @@
 KETRICS_TOKEN=ktd_your-token-id_your-secret-key
 
 # API URL (default for production)
-KETRICS_API_URL=https://api.ketrics.cl/api/v1
+KETRICS_API_URL=https://api.ketrics.io/api/v1
 
 # Your tenant ID
 KETRICS_TENANT_ID=your-tenant-uuid

package/templates/ketrics-app-v1/README.md

@@ -10,7 +10,7 @@ test-application/
 │   ├── src/
 │   ├── ketrics.config.json
 │   └── .env.example
-└── backend/           # TypeScript handlers for data-plane
+└── backend/           # TypeScript handlers for runtime-api
     ├── src/
     ├── ketrics.config.json
     └── .env.example
@@ -47,7 +47,7 @@ npm run build
 
 ## Backend
 
-TypeScript handlers compatible with Ketrics data-plane-api.
+TypeScript handlers compatible with Ketrics runtime-api-api.
 
 ### Available Actions
 

package/templates/ketrics-app-v1/backend/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * Ketrics Application Backend
  *
- * Exports handler functions compatible with Ketrics data-plane-api.
+ * Exports handler functions compatible with Ketrics runtime-api.
  *
  * The `ketrics` global object is automatically typed via @ketrics/sdk.
  * No imports needed - just use `ketrics.*` directly.

package/templates/ketrics-app-v1/backend/src/volume.ts

@@ -4,7 +4,7 @@ const saveFile = async () => {
   const data = {
     id: ketrics.application.id,
     code: ketrics.application.code,
-    name: ketrics.application.name,
+    applicationName: ketrics.application.applicationName,
     version: ketrics.application.version,
     deploymentId: ketrics.application.deploymentId,
   };