@appweaver/cli 1.0.0

package/skill/references/dependency-injection.md

@@ -0,0 +1,214 @@
+# Dependency Injection
+
+The application context provides a lightweight dependency injection (DI) system through `define` and `inject`. Values,
+class constructors, and singleton instances are stored in the context and resolved by name or class reference.
+
+#### `define(value, nameOrClass?, mode?)`
+
+Registers a value or class constructor in the application context.
+
+| Parameter     | Type                                           | Description                                                                                           |
+|---------------|------------------------------------------------|-------------------------------------------------------------------------------------------------------|
+| `value`       | any                                            | The value, instance, or class constructor to register                                                 |
+| `nameOrClass` | `string \| symbol \| Class \| Function`        | Token used to look up this definition. Defaults to the value's class name or `RESOURCE_NAME` property |
+| `mode`        | `'ignore' \| 'override' \| 'append' \| 'fail'` | How to handle duplicates. Defaults to `'ignore'`                                                      |
+
+**Register a plain value with a string token:**
+
+```ts
+import { define } from '@appweaver/core';
+
+define('https://api.example.com', 'ApiBaseUrl');
+```
+
+**Register a class instance under an abstract class token:**
+
+```ts
+import { define } from '@appweaver/core';
+import { SecurityStore } from '@appweaver/common';
+import { RedisSecurityStore } from './redis-security-store';
+
+// RedisSecurityStore will be looked up by SecurityStore.name
+define(new RedisSecurityStore(), SecurityStore);
+```
+
+**Register a class constructor (lazy instantiation on the first injection):**
+
+```ts
+import { define } from '@appweaver/core';
+import { Cache } from '@appweaver/common';
+import { RedisCacheService } from './redis-cache-service';
+
+// RedisCacheService is instantiated the first time inject(Cache) is called
+define(RedisCacheService, Cache);
+```
+
+**Register with a symbol token:**
+
+```ts
+import { define } from '@appweaver/core';
+
+const RATE_LIMITER = Symbol('RateLimiter');
+define(new TokenBucketLimiter(), RATE_LIMITER);
+```
+
+**Override an existing definition:**
+
+```ts
+import { define } from '@appweaver/core';
+import { Cache } from '@appweaver/common';
+
+define(new InMemoryCacheService(), Cache, 'override');
+```
+
+#### `inject(nameOrClass, required?)`
+
+Retrieves a definition from the application context. If the stored value is a class constructor, it is instantiated on
+first access, and the instance replaces the constructor in the context (singleton pattern).
+
+| Parameter     | Type                                    | Description                            |
+|---------------|-----------------------------------------|----------------------------------------|
+| `nameOrClass` | `string \| symbol \| Class \| Function` | Token that identifies the definition   |
+| `required`    | `boolean`                               | Throw if not found. Defaults to `true` |
+
+**Inject by abstract class (the most common pattern):**
+
+```ts
+import { inject } from '@appweaver/core';
+import { SecurityStore } from '@appweaver/common';
+
+export class AuthService {
+  private readonly _store = inject(SecurityStore);
+}
+```
+
+**Inject by string token:**
+
+```ts
+import { inject } from '@appweaver/core';
+
+const apiUrl = inject<string>('ApiBaseUrl');
+```
+
+**Inject by symbol token:**
+
+```ts
+import { inject } from '@appweaver/core';
+
+const RATE_LIMITER = Symbol('RateLimiter');
+const limiter = inject<RateLimiter>(RATE_LIMITER);
+```
+
+**Optionally inject (returns `undefined` instead of throwing):**
+
+```ts
+import { inject } from '@appweaver/core';
+import { Mailer } from '@appweaver/common';
+
+const mailer = inject(Mailer, false); // undefined if not registered
+if (mailer) {
+  await mailer.send(message);
+}
+```
+
+**Real-world example — service using injected dependencies:**
+
+```ts
+// src/features/notifications/notification-service.ts
+import { inject } from '@appweaver/core';
+import { Mailer, Cache } from '@appweaver/common';
+import { CacheService } from '@appweaver/core';
+
+export class NotificationService {
+  private readonly _mailer = inject(Mailer);
+  private readonly _cache = inject(CacheService);
+
+  async notify(userId: number, message: string) {
+    const key = `notification:${userId}`;
+    if (await this._cache.getCachedValue(key)) return;
+    await this._mailer.send({ to: userId, body: message });
+    await this._cache.addToCache(key, true, 60_000);
+  }
+}
+```
+
+Then register it so other code can inject it:
+
+```ts
+import { define } from '@appweaver/core';
+import { NotificationService } from './notification-service';
+
+define(NotificationService);
+// or define the instance directly:
+define(new NotificationService(), NotificationService);
+```
+
+#### `loadProvider(baseDir, classPath, definition?, required?)`
+
+Dynamically loads a class from a file path and registers it in the context. The first exported constructor in the
+resolved module is used. This is the standard way to load infrastructure provider implementations that are configured
+via environment-specific paths.
+
+| Parameter    | Type      | Description                                                                          |
+|--------------|-----------|--------------------------------------------------------------------------------------|
+| `baseDir`    | `string`  | Base directory for resolving relative paths                                          |
+| `classPath`  | `string`  | Path to the module — relative to `baseDir`, project source path, or npm package name |
+| `definition` | `Class`   | Abstract class / token to register the loaded class under                            |
+| `required`   | `boolean` | Throw on load failure. Defaults to `true`                                            |
+
+**Load a provider and register it under an abstract token:**
+
+```ts
+import { loadProvider } from '@appweaver/core';
+import { Database } from '@appweaver/common';
+
+// Loads the first exported class from './providers/postgres-database.ts'
+// and registers it as Database
+loadProvider(__dirname, './providers/postgres-database', Database);
+```
+
+**Load an optional provider (no error if the file is missing):**
+
+```ts
+import { loadProvider } from '@appweaver/core';
+import { Queue } from '@appweaver/common';
+
+loadProvider(__dirname, config.QUEUE_PROVIDER, Queue, false);
+```
+
+**Load a provider from an NPM package:**
+
+```ts
+import { loadProvider } from '@appweaver/core';
+import { Cache } from '@appweaver/common';
+
+loadProvider(__dirname, '@myorg/redis-cache', Cache);
+```
+
+**Loading multiple providers at startup (typical `main.ts` pattern):**
+
+```ts
+// src/main.ts
+import { loadProvider } from '@appweaver/core';
+import { Database, Cache, Mailer } from '@appweaver/common';
+import { config } from '@appweaver/common';
+
+// Required infrastructure
+loadProvider(__dirname, config.DATABASE_PROVIDER, Database);
+loadProvider(__dirname, config.CACHE_PROVIDER, Cache);
+
+// Optional infrastructure
+loadProvider(__dirname, config.MAILER_PROVIDER, Mailer, false);
+
+// Internal feature service (no token — registered by its own class name)
+loadProvider(__dirname, '../notifications/notification-service', undefined, false);
+```
+
+After `loadProvider` runs, the loaded class is available via `inject`:
+
+```ts
+import { inject } from '@appweaver/core';
+import { Database } from '@appweaver/common';
+
+const db = inject(Database); // resolves the class loaded from config.DATABASE_PROVIDER
+```

package/skill/references/events.md

@@ -0,0 +1,152 @@
+# Events
+
+The events module provides a resource-scoped publish/subscribe system built on top of Node.js `EventEmitter`. It is used
+internally by the framework to broadcast resource lifecycle changes (`create`, `update`, `delete`, `get`, `list`) and
+can be used directly to react to those events anywhere in the application.
+
+## Injecting Events
+
+```ts
+import { inject } from '@appweaver/core';
+import { Events } from '@appweaver/common';
+
+const events = inject(Events);
+```
+
+---
+
+#### `events.onResourceEvent<T>(resourceName, event, listener)`
+
+Registers a listener for a specific resource and action. Returns a listener ID that can be used to unsubscribe.
+
+| Parameter      | Type               | Description                                           |
+|----------------|--------------------|-------------------------------------------------------|
+| `resourceName` | `string`           | The name of the resource model (e.g. `'Product'`)     |
+| `event`        | `ActionType`       | `'create'`, `'update'`, `'delete'`, `'get'`, `'list'` |
+| `listener`     | `EventListener<T>` | Callback receiving `EventData<T>`                     |
+
+`EventData<T>` shape:
+
+```ts
+type EventData<T> = {
+  previous?: T; // present on 'update' and 'delete'
+  current: T;
+};
+```
+
+```ts
+const listenerId = events.onResourceEvent<Product>('Product', 'create', ({ current }) => {
+  logger.info('New product created:', current.name);
+});
+```
+
+**Listening to updates** (access both previous and current state):
+
+```ts
+events.onResourceEvent<User>('User', 'update', ({ previous, current }) => {
+  if (previous?.email !== current.email) {
+    sendEmailChangeNotification(current);
+  }
+});
+```
+
+---
+
+#### `events.emitResourceEvent<T>(resourceName, event, data)`
+
+Emits an event for a resource. The framework calls this automatically after every resource mutation; use it directly
+only when you need to emit custom events from your own service logic.
+
+| Parameter      | Type           | Description                                     |
+|----------------|----------------|-------------------------------------------------|
+| `resourceName` | `string`       | Resource model name                             |
+| `event`        | `ActionType`   | Action type                                     |
+| `data`         | `EventData<T>` | Object with `current` (and optional `previous`) |
+
+```ts
+events.emitResourceEvent<Order>('Order', 'create', { current: newOrder });
+```
+
+---
+
+#### `events.removeResourceEvent(listenerId)`
+
+Unregisters a listener by the ID returned from `onResourceEvent`. Returns `true` if the listener was found and removed.
+
+```ts
+const listenerId = events.onResourceEvent('Product', 'delete', handler);
+// ... later:
+events.removeResourceEvent(listenerId);
+```
+
+---
+
+## Configuration
+
+| Key                    | Type     | Default                                | Description                           |
+|------------------------|----------|----------------------------------------|---------------------------------------|
+| `EVENTS_MAX_LISTENERS` | `int`    | `10`                                   | Max listeners per event (Node.js cap) |
+| `EVENTS_PROVIDER`      | `string` | `'@appweaver/core/events/node-events'` | Path to the Events implementation     |
+
+## Real-world example
+
+Register listeners at startup, then let the framework drive the emit side:
+
+```ts
+// src/features/notifications/notification-listener.ts
+import { inject } from '@appweaver/core';
+import { Events, logger, Mailer } from '@appweaver/common';
+
+export function registerNotificationListeners() {
+  const events = inject(Events);
+  const mailer = inject(Mailer, false);
+
+  events.onResourceEvent<Order>('Order', 'create', async ({ current }) => {
+    if (!mailer) return;
+    await mailer.sendEmail({
+      to: current.customerEmail,
+      subject: 'Order received',
+      text: `Your order #${current.id} has been placed.`
+    });
+  });
+
+  events.onResourceEvent<User>('User', 'delete', ({ current }) => {
+    logger.info(`User ${current.id} was deleted — cleaning up sessions`);
+    cleanupSessions(current.id);
+  });
+}
+```
+
+Call `registerNotificationListeners()` during application startup, after the providers are loaded.
+
+---
+
+## Using Node.js EventEmitter directly
+
+Since `Events` extends Node.js `EventEmitter`, you can use the standard `.on()` / `.emit()` API for custom application
+events alongside the resource event helpers.
+
+```ts
+import { inject } from '@appweaver/core';
+import { Events } from '@appweaver/common';
+
+const events = inject(Events);
+
+// Listen for a custom event
+events.on('user-registered', (user: User) => {
+  logger.info(`Welcome email queued for ${user.email}`);
+  mailer.sendWelcomeEmail(user);
+});
+
+// Emit the event from your service
+events.emit('user-registered', newUser);
+```
+
+You can use any string as the event name. The listener receives whatever arguments you pass to `emit`. Use
+`events.once()` if you only need to handle the event one time:
+
+```ts
+events.once('user-registered', (user: User) => {
+  logger.info(`First registration ever: ${user.email}`);
+});
+```

package/skill/references/mailer.md

@@ -0,0 +1,235 @@
+# Mailer
+
+The mailer module sends transactional emails. The default implementation (`SmtpMailer`) uses Nodemailer over SMTP. A
+`JsonMailer` is available for development and tests — it returns a JSON representation of the email instead of sending
+it.
+
+## Injecting Mailer
+
+Mailer is an optional infrastructure. Inject it with `required: false` to avoid errors when no mailer is configured.
+
+```ts
+import { inject } from '@appweaver/core';
+import { Mailer } from '@appweaver/common';
+
+const mailer = inject(Mailer, false); // undefined if not registered
+```
+
+---
+
+#### `mailer.sendEmail(data)`
+
+Sends an email. Returns `true` on success.
+
+| Field         | Type           | Required | Description                               |
+|---------------|----------------|----------|-------------------------------------------|
+| `to`          | `string`       | Yes      | Recipient address                         |
+| `subject`     | `string`       | Yes      | Email subject line                        |
+| `text`        | `string`       | Yes      | Plain-text body                           |
+| `html`        | `string`       | No       | HTML body (falls back to wrapping `text`) |
+| `attachments` | `Attachment[]` | No       | Provider-specific attachment objects      |
+
+```ts
+await mailer.sendEmail({
+  to: 'alice@example.com',
+  subject: 'Welcome!',
+  text: 'Thanks for signing up.',
+  html: '<p>Thanks for <strong>signing up</strong>.</p>'
+});
+```
+
+**With attachments** (Nodemailer format for SmtpMailer):
+
+```ts
+await mailer.sendEmail({
+  to: 'bob@example.com',
+  subject: 'Your invoice',
+  text: 'Please find your invoice attached.',
+  attachments: [
+    { filename: 'invoice.pdf', path: '/tmp/invoice.pdf' }
+  ]
+});
+```
+
+---
+
+#### `mailer.checkHealth()`
+
+Verifies that the mail transport is reachable (`transporter.verify()` for SMTP). Returns a `HealthCheckResult`.
+
+---
+
+## Configuration
+
+| Key                     | Type     | Default                                | Description                       |
+|-------------------------|----------|----------------------------------------|-----------------------------------|
+| `MAILER_PROVIDER`       | `string` | `'@appweaver/core/mailer/smtp-mailer'` | Path to the Mailer implementation |
+| `MAILER_SENDER_NAME`    | `string` | —                                      | Display name of the sender        |
+| `MAILER_SENDER_ADDRESS` | `string` | —                                      | From address                      |
+| `MAILER_SMTP_HOST`      | `string` | `'127.0.0.1'`                          | SMTP server hostname              |
+| `MAILER_SMTP_PORT`      | `int`    | `587`                                  | SMTP server port                  |
+| `MAILER_SMTP_SECURE`    | `bool`   | `false`                                | Use TLS (`true` for port 465)     |
+| `MAILER_SMTP_USER`      | `string` | —                                      | SMTP authentication username      |
+| `MAILER_SMTP_PASSWORD`  | `string` | —                                      | SMTP authentication password      |
+
+**`appweaver.json` example:**
+
+```json
+{
+  "MAILER_SENDER_NAME": "My App",
+  "MAILER_SENDER_ADDRESS": "no-reply@myapp.com",
+  "MAILER_SMTP_HOST": "smtp.mailgun.org",
+  "MAILER_SMTP_PORT": 587,
+  "MAILER_SMTP_USER": "postmaster@mg.myapp.com",
+  "MAILER_SMTP_PASSWORD": "secret"
+}
+```
+
+**Use `JsonMailer` in development or tests:**
+
+```json
+{
+  "MAILER_PROVIDER": "@appweaver/core/mailer/json-mailer"
+}
+```
+
+---
+
+## Real-world example
+
+```ts
+import { inject } from '@appweaver/core';
+import { Mailer } from '@appweaver/common';
+
+export class AuthService {
+  private readonly _mailer = inject(Mailer, false);
+
+  async sendPasswordReset(email: string, token: string): Promise<void> {
+    if (!this._mailer) return; // mailer not configured, skip silently
+
+    await this._mailer.sendEmail({
+      to: email,
+      subject: 'Reset your password',
+      text: `Use this token to reset your password: ${token}`,
+      html: `<p>Use this token to reset your password: <strong>${token}</strong></p>`
+    });
+  }
+}
+```
+
+---
+
+## EmailService
+
+`EmailService` is a higher-level wrapper around `Mailer` that routes all emails through the `Queue` infrastructure. This
+decouples the caller from the SMTP transport, provides retry semantics, and avoids blocking the request thread on email
+delivery.
+
+Inject it like any other service — no `required: false` needed since it is always registered when the mailer module is
+loaded.
+
+```ts
+import { EmailService, inject } from '@appweaver/core';
+```
+
+---
+
+#### `emailService.sendEmail(email)`
+
+Fire-and-forget. Adds the email to the queue and returns immediately — delivery happens asynchronously.
+
+```ts
+await emailService.sendEmail({
+  to: 'alice@example.com',
+  subject: 'Welcome!',
+  text: 'Thanks for signing up.',
+  html: '<p>Thanks for <strong>signing up</strong>.</p>'
+});
+```
+
+---
+
+#### `emailService.sendEmailAndWait(email)`
+
+Queues the email and resolves only once delivery succeeds, or rejects if it fails. Use this when you need a delivery
+confirmation before proceeding (e.g., before returning a 200 to the client).
+
+Returns `true` on success.
+
+```ts
+const sent = await emailService.sendEmailAndWait({
+  to: 'bob@example.com',
+  subject: 'Your invoice',
+  text: 'Please find your invoice attached.',
+  attachments: [{ filename: 'invoice.pdf', path: '/tmp/invoice.pdf' }]
+});
+```
+
+---
+
+#### `emailService.sendEmailBulk(emails)`
+
+Queues all emails at once without waiting for any to finish. Prefer this when sending a large batch and delivery
+confirmation is not required.
+
+```ts
+await emailService.sendEmailBulk(
+  users.map((u) => ({
+    to: u.email,
+    subject: 'New feature announcement',
+    text: `Hi ${u.name}, we just shipped something new...`
+  }))
+);
+```
+
+---
+
+#### `emailService.sendEmailBulkAndWait(emails)`
+
+Queues all emails and waits for every delivery attempt to settle. Returns an array of
+`{ success: boolean; error?: Error }` in the same order as the input — failed deliveries do not reject the whole call.
+
+```ts
+const results = await emailService.sendEmailBulkAndWait(emails);
+
+for (const [i, result] of results.entries()) {
+  if (!result.success) {
+    logger.error(result.error, `Failed to deliver email to ${emails[i].to}`);
+  }
+}
+```
+
+---
+
+### Real-world example — post-registration flow
+
+```ts
+import { EmailService, inject } from '@appweaver/core';
+
+export class RegistrationService {
+  private readonly _emailService = inject(EmailService);
+
+  async register(user: { email: string; name: string }): Promise<void> {
+    // ... persist user to DB ...
+
+    // Send welcome email and wait for confirmation before returning
+    await this._emailService.sendEmailAndWait({
+      to: user.email,
+      subject: 'Welcome to MyApp!',
+      text: `Hi ${user.name}, your account is ready.`,
+      html: `<p>Hi <strong>${user.name}</strong>, your account is ready.</p>`
+    });
+  }
+
+  async notifyAdmins(admins: { email: string }[], message: string): Promise<void> {
+    // Blast all admin notifications without blocking
+    await this._emailService.sendEmailBulk(
+      admins.map((a) => ({
+        to: a.email,
+        subject: 'Admin notification',
+        text: message
+      }))
+    );
+  }
+}
+```