update docs for starter packages

Author: manusant

starters/actuator/README.md

@@ -3,20 +3,27 @@
 [![npm version](https://img.shields.io/npm/v/@nodeboot/starter-actuator.svg)](https://www.npmjs.com/package/@nodeboot/starter-actuator)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Node-Boot Actuator Starter** provides production-ready monitoring, health checks, and application insights for Node-Boot applications, following Spring Boot Actuator patterns for the Node.js ecosystem.
+> **Node-Boot Actuator Starter** provides production-ready monitoring, health checks, and application insights for
+> Node-Boot applications, following Spring Boot Actuator patterns for the Node.js ecosystem.
 
 ## Overview
 
-The Node-Boot Actuator Starter brings comprehensive application monitoring and observability to your Node.js applications. It automatically exposes operational endpoints for health checks, metrics collection, application information, and more. This starter is the Node.js equivalent of Spring Boot Actuator, providing the same level of production-ready monitoring capabilities.
+The Node-Boot Actuator Starter brings comprehensive application monitoring and observability to your Node.js
+applications. It automatically exposes an `/actuator` family of operational endpoints for health checks, Prometheus
+metrics, build/git information, memory diagnostics, and introspection of your application's controllers,
+interceptors and middlewares — with zero manual route wiring.
 
 ### Key Features
 
-✅ **Auto-Configuration** – Zero-configuration setup with sensible defaults  
-✅ **Health Checks** – Built-in health endpoints with custom health indicators  
-✅ **Prometheus Metrics** – Automatic metrics collection and exposure  
-✅ **Application Info** – Git information, build details, and environment data  
-✅ **Multi-Framework Support** – Works with Express, Fastify, Koa, and native HTTP  
-✅ **Production-Ready** – Battle-tested monitoring patterns from Spring Boot
+✅ **Auto-Configuration** – Zero-configuration setup, endpoints are bound automatically at bootstrap  
+✅ **Health Checks** – Liveness/readiness endpoints that reflect real application lifecycle state  
+✅ **Prometheus Metrics** – Default Node.js process metrics plus HTTP request count/duration histograms  
+✅ **Application Info** – Runtime info (host, Node version, uptime, active profiles) and build metadata from
+`package.json`  
+✅ **Git Info** – Optional endpoint exposing commit/branch metadata from a `git.properties` file  
+✅ **Introspection Endpoints** – Inspect registered controllers, interceptors, and middlewares at runtime  
+✅ **Multi-Framework Support** – Works with Express, Fastify, Koa, and native `http` servers  
+✅ **Production-Ready** – Battle-tested monitoring patterns from Spring Boot Actuator
 
 ---
 
@@ -25,8 +32,9 @@ The Node-Boot Actuator Starter brings comprehensive application monitoring and o
 ### Prerequisites
 
 -   Node.js 18+
--   Node-Boot 2.0+
--   One of the supported servers: Express, Fastify, Koa, or native HTTP
+-   A Node-Boot application using one of the supported servers: Express, Fastify, Koa, or native HTTP
+-   `@EnableDI(Container)` on your application class — the actuator resolves core services (`ConfigService`,
+    `CoreInfoService`, `HealthService`, `Logger`) from the DI container and **throws at bootstrap** if it's missing
 
 ### Install the Starter
 
@@ -41,53 +49,164 @@ npm install @nodeboot/starter-actuator
 yarn add @nodeboot/starter-actuator
 ```
 
-### Auto-Configuration
-
-This starter provides auto-configuration when added to your Node-Boot application. No additional setup required for basic usage.
-
 ---
 
 ## ⚡ Quick Start
 
 ### 1️⃣ Enable Actuator in Your Application
 
 ```typescript
-import {NodeBootApplication, NodeBoot, ExpressServer} from "@nodeboot/core";
+import "reflect-metadata";
+import {Container} from "typedi";
+import {NodeBoot, NodeBootApp, NodeBootApplication, NodeBootAppView} from "@nodeboot/core";
+import {ExpressServer} from "@nodeboot/express-server";
+import {EnableDI} from "@nodeboot/di";
+import {EnableComponentScan} from "@nodeboot/aot";
 import {EnableActuator} from "@nodeboot/starter-actuator";
 
+@EnableDI(Container)
 @EnableActuator()
+@EnableComponentScan()
 @NodeBootApplication()
-export class Application {
+export class Application implements NodeBootApp {
     start(): Promise<NodeBootAppView> {
         return NodeBoot.run(ExpressServer);
     }
 }
 ```
 
-### 2️⃣ Basic Usage
-
-Once enabled, the actuator automatically exposes monitoring endpoints:
+`@EnableActuator()` registers an `ActuatorAdapter` on the application context. At bootstrap, the framework picks the
+concrete adapter implementation (Express/Fastify/Koa/native HTTP) matching your chosen server and binds all
+`/actuator/*` routes directly on your application's router — no extra wiring required.
 
-### 3️⃣ Verify Setup
+### 2️⃣ Verify Setup
 
 ```bash
 # Start your application
 pnpm start
 
 # Access the actuator endpoints:
-# Health check
 curl http://localhost:3000/actuator/health
-
-# Application info
 curl http://localhost:3000/actuator/info
-
-# Prometheus metrics
 curl http://localhost:3000/actuator/metrics
+curl http://localhost:3000/actuator/prometheus
 
 # Look for these log messages indicating successful setup:
-# ✅ Actuator endpoints enabled
-# ✅ Health checks registered
-# ✅ Metrics collection started
+# =====> 🏭 Actuator is Active :) = http://localhost:3000/actuator
+# =====> 🚥 Prometheus monitoring endpoint is live :) = http://localhost:3000/actuator/prometheus
+```
+
+---
+
+## 📡 Available Endpoints
+
+| Endpoint                         | Description                                                                                      |
+| -------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `GET /actuator`                  | Lists all available actuator endpoints.                                                          |
+| `GET /actuator/info`             | Runtime info: hostname, Node version, load average, uptime, active profiles, build info.         |
+| `GET /actuator/git`              | Git branch/commit metadata, read from a `git.properties` file (see below).                       |
+| `GET /actuator/config`           | The fully resolved application configuration (see ⚠️ security note below).                       |
+| `GET /actuator/memory`           | Memory diagnostics: `os.freemem/totalmem`, `process.memoryUsage()`, V8 heap statistics.          |
+| `GET /actuator/metrics`          | All registered Prometheus metrics, as JSON.                                                      |
+| `GET /actuator/prometheus`       | All registered Prometheus metrics, in Prometheus text exposition format.                         |
+| `GET /actuator/controllers`      | Introspection of all registered Node-Boot controllers, routes, and actions.                      |
+| `GET /actuator/interceptors`     | Introspection of all registered interceptors.                                                    |
+| `GET /actuator/middlewares`      | Introspection of all registered middlewares.                                                     |
+| `GET /actuator/health`           | Combined readiness + liveness payload, plus links to the individual endpoints below.             |
+| `GET /actuator/health/readiness` | `200` once the app (and persistence layer, if enabled) has finished starting; `503` otherwise.   |
+| `GET /actuator/health/liveness`  | Always `200 {"status": "ok"}` while the process is running — suitable for basic liveness probes. |
+
+## ❤️ Health Checks and Application Lifecycle
+
+`/actuator/health/readiness` is not a static "OK" — it's wired to Node-Boot's application lifecycle:
+
+-   If `@nodeboot/starter-persistence` (`@EnableRepositories()`) is **not** enabled, readiness flips to `true` as
+    soon as the `application.started` lifecycle event fires.
+-   If persistence **is** enabled, readiness stays `503 {"message": "Backend has not started yet"}` until the
+    `persistence.started` event fires (i.e. the datasource has actually connected), so orchestrators (Kubernetes,
+    ECS, ...) won't route traffic to an instance whose database connection isn't ready yet.
+-   `/actuator/health/liveness` always reports `200`, and is intended purely to detect whether the process itself is
+    alive/hung — use `readiness` for traffic-routing decisions and `liveness` for restart decisions.
+
+```bash
+curl http://localhost:3000/actuator/health/readiness
+# {"status":"ok"}                                     # once ready
+# {"message":"Backend has not started yet","status":"error"}  (HTTP 503, before ready)
+```
+
+## 📈 Prometheus Metrics
+
+The actuator registers a dedicated `prom-client` `Registry` and collects:
+
+-   **Default Node.js process metrics** (event loop lag, GC duration, memory, CPU, etc.) via
+    `Prometheus.collectDefaultMetrics()`.
+-   **`app_http_request_count`** — a `Counter` labeled by `method`, `route`, and `statusCode`, incremented on every
+    request that finishes.
+-   **`app_http_request_duration_milliseconds`** — a `Histogram` labeled by `method`, `route`, and `code`, recording
+    request duration.
+
+Metrics recording is offloaded via `setImmediate` so it never blocks the response.
+
+```bash
+# Prometheus text format, ready to be scraped:
+curl http://localhost:3000/actuator/prometheus
+
+# Same metrics as JSON:
+curl http://localhost:3000/actuator/metrics
+```
+
+Point your Prometheus `scrape_configs` at `/actuator/prometheus` to start collecting these metrics.
+
+## 🌱 Git Info
+
+`/actuator/git` follows the same convention as Spring Boot's `git-commit-id-plugin`: it reads a `git.properties`
+file from your application's working directory (via the `properties-reader` library) with keys such as:
+
+```properties
+git.branch=main
+git.commit.id=1a2b3c4d5e6f7890abcdef1234567890abcdef12
+git.commit.id.abbrev=1a2b3c4
+git.commit.time=2025-01-15T10:30:00Z
+git.commit.user.name=Jane Doe
+git.commit.user.email=jane@example.com
+git.commit.message.full=Fix actuator health check
+git.commit.message.short=Fix actuator health check
 ```
 
-TO BE CONTINUED...
+Node-Boot itself does not generate this file — since there's no Node.js equivalent of the Maven/Gradle
+`git-commit-id-plugin`, generate it yourself as a prebuild step, for example:
+
+```json
+{
+    "scripts": {
+        "generate:git-info": "echo \"git.branch=$(git rev-parse --abbrev-ref HEAD)\ngit.commit.id=$(git rev-parse HEAD)\ngit.commit.id.abbrev=$(git rev-parse --short HEAD)\ngit.commit.time=$(git log -1 --format=%cI)\" > git.properties",
+        "prebuild": "pnpm run generate:git-info"
+    }
+}
+```
+
+If `git.properties` is missing, `/actuator/git` simply returns `undefined`/an empty body instead of failing.
+
+## ⚠️ Security Note on `/actuator/config`
+
+`/actuator/config` returns your **entire resolved configuration tree**, including any secrets interpolated from
+environment variables at load time. Treat all `/actuator/*` endpoints as internal/operational surface: put them
+behind network-level restrictions (VPC, internal load balancer, sidecar auth) or a reverse-proxy rule, rather than
+exposing them on the public internet alongside your API.
+
+## 🖥️ Framework Support
+
+The actuator binds routes through a framework-specific adapter chosen automatically based on which Node-Boot server
+you use (`ExpressServer`, `FastifyServer`, `KoaServer`, or `HttpServer`). If `@EnableActuator()` is applied with an
+unsupported server type, bootstrap fails fast with a clear error asking you to remove the decorator.
+
+## 🎉 Conclusion
+
+`@nodeboot/starter-actuator` brings Spring Boot Actuator-style production readiness to Node-Boot applications:
+health checks tied to real lifecycle state, Prometheus metrics out of the box, and introspection endpoints for
+controllers, interceptors and middlewares — all with a single `@EnableActuator()` decorator.
+
+## 📚 Resources
+
+-   [Spring Boot Actuator (reference inspiration)](https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html)
+-   [prom-client (Prometheus client for Node.js)](https://github.com/siimon/prom-client)

starters/aws/README.md

@@ -7,7 +7,7 @@ dependency injection and auto-configuration for AWS clients such as DynamoDB, S3
 
 ## Enabling AWS Services
 
-1. Firs install the AWS Starter package for NodeBoot:
+1. First install the AWS Starter package for NodeBoot:
 
 ```sh
 npm install @nodeboot/starter-aws
@@ -21,7 +21,7 @@ import {Container} from "typedi";
 import {NodeBoot, NodeBootApp, NodeBootApplication, NodeBootAppView} from "@nodeboot/core";
 import {ExpressServer} from "@nodeboot/express-server";
 import {EnableDI} from "@nodeboot/di";
-import {EnableComponentScan} from "@nodeboot/scan";
+import {EnableComponentScan} from "@nodeboot/aot";
 import {EnableAws} from "@nodeboot/starter-aws";
 
 @EnableDI(Container)
@@ -93,6 +93,10 @@ region=us-east-1
 > to
 > [Setting_AWS_Credentials](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/configuring-the-jssdk.html#Setting_AWS_Credentials)
 
+> ⚠️ If `integrations.aws.credentials` is not set in `app-config.yaml`, each client is still created — the starter
+> logs a warning and falls back to the AWS SDK's default credentials provider chain (environment variables, shared
+> `~/.aws/credentials` file, or an attached IAM role), so explicit config is optional in environments like EC2/ECS/Lambda.
+
 ## AWS Service-Specific Instructions
 
 ### DynamoDB
@@ -299,6 +303,31 @@ com:
                 queue-url: "https://sqs.us-east-1.amazonaws.com/123456789012/my-queue"
 ```
 
+> `@SqsListener` only registers when the current active profiles satisfy any `@Profile(...)` metadata declared on the
+> target class (see `@nodeboot/core`'s `@Profile` decorator). If the profiles don't match, or AWS SQS isn't enabled
+> via `@EnableAws()`/`integrations.aws.sqs.region`, the listener logs a warning and is skipped instead of throwing.
+
+#### The `MessageEnvelop` Payload
+
+Every `@SqsListener` handler receives a `MessageEnvelop<M>` — a parsed wrapper around the raw SQS message body,
+rather than the raw `sqs-consumer` `Message` object:
+
+```typescript
+type MessageEnvelop<M = JsonObject> = {
+    messageId: string; // AWS-assigned message ID
+    timestamp: string; // SNS/SQS delivery timestamp
+    signature: string; // SNS signature, when the message originated from an SNS->SQS subscription
+    message: M; // The actual, JSON-parsed message payload
+};
+```
+
+```typescript
+@SqsListener("${com.example.aws.sqs.queue-url}")
+async onMessage(envelop: MessageEnvelop<{orderId: string}>): Promise<void> {
+    console.log(`Processing order ${envelop.message.orderId} (messageId=${envelop.messageId})`);
+}
+```
+
 #### SQS Message Handling
 
 -   The queue is polled continuously for messages using [long polling](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-long-polling.html).