@mariachi/core 0.0.1

package/docs/recipes/add-webhook-endpoint.md

@@ -0,0 +1,169 @@
+# Recipe: Add a Webhook Endpoint
+
+This walks through creating a webhook endpoint that receives callbacks from third-party services (e.g. Stripe, GitHub). Mariachi's `@mariachi/webhooks` package provides `WebhookController` with two processing modes: `direct` (synchronous via communication layer) and `queue` (asynchronous via job queue).
+
+---
+
+## Overview
+
+```
+Third-party POST → WebhookServer → AuthController.auth() → WebhookController handler
+                                                            ├── mode: 'direct' → communication.call(procedure, payload)
+                                                            └── mode: 'queue'  → jobQueue.enqueue(jobName, payload)
+```
+
+All webhooks are logged via `WebhookLogStore`.
+
+---
+
+## 1. Create an Auth Controller
+
+Each webhook controller needs an `AuthController` that verifies the incoming request. Extend either `ApiKeyAuthController` or `OAuthAuthController`.
+
+**File:** e.g. `src/webhooks/github-auth.ts`
+
+```ts
+import type { RequestContext } from '@mariachi/server';
+import { ApiKeyAuthController } from '@mariachi/webhooks';
+
+export class GitHubWebhookAuth extends ApiKeyAuthController {
+  readonly provider = 'github';
+  protected readonly headerName = 'x-hub-signature-256';
+
+  protected async verify(signature: string, ctx: RequestContext): Promise<boolean> {
+    // Verify the HMAC signature against the webhook secret
+    return signature.length > 0;
+  }
+}
+```
+
+**Auth controller types:**
+- `ApiKeyAuthController` — verifies a header value. Override `headerName` for custom headers.
+- `OAuthAuthController` — verifies a Bearer token.
+- Custom: extend `AuthController` directly and implement `auth(req, ctx)`.
+
+---
+
+## 2. Create the Webhook Controller
+
+Extend `WebhookController` with a `prefix`, `auth`, and route definitions in `init()`.
+
+**File:** e.g. `src/webhooks/github.controller.ts`
+
+```ts
+import { WebhookController, type WebhookContext, type WebhookRouteOpts } from '@mariachi/webhooks';
+import { GitHubWebhookAuth } from './github-auth';
+
+export class GitHubWebhookController extends WebhookController {
+  readonly prefix = 'github';
+  readonly auth = new GitHubWebhookAuth();
+
+  init() {
+    this.post(this.buildPath('push'), {
+      mode: 'direct',
+      procedure: 'github.handlePush',
+      ttl: '30d',
+    }, this.handlePush);
+
+    this.post(this.buildPath('issue'), {
+      mode: 'queue',
+      jobName: 'github.processIssue',
+      ttl: '30d',
+    }, this.handleIssue);
+  }
+
+  handlePush = async (ctx: WebhookContext, body: unknown) => {
+    ctx.logger.info('Received GitHub push webhook');
+    return body;
+  };
+
+  handleIssue = async (ctx: WebhookContext, body: unknown) => {
+    ctx.logger.info('Received GitHub issue webhook');
+    return body;
+  };
+}
+```
+
+**Route options (`WebhookRouteOpts`):**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `mode` | Yes | `'direct'` (sync) or `'queue'` (async) |
+| `procedure` | When `mode: 'direct'` | Communication procedure name |
+| `jobName` | When `mode: 'queue'` | Job name for `@mariachi/jobs` |
+| `ttl` | No | Log retention duration (e.g. `'7d'`, `'30d'`) |
+
+---
+
+## 3. Register on a WebhookServer
+
+**File:** e.g. `src/index.ts`
+
+```ts
+import { WebhookServer } from '@mariachi/webhooks';
+import { GitHubWebhookController } from './webhooks/github.controller';
+
+const webhookServer = new WebhookServer(
+  { name: 'webhooks', defaultTtl: '7d' },
+  { communication, jobQueue, logStore },
+);
+
+webhookServer.registerController(new GitHubWebhookController());
+
+startup.register({
+  name: 'webhook-server',
+  priority: 100,
+  fn: async () => {
+    await webhookServer.listen(WEBHOOK_PORT);
+  },
+});
+```
+
+---
+
+## 4. Register the Handler or Job
+
+**For `mode: 'direct'`** — register a communication handler:
+
+```ts
+communication.register('github.handlePush', {
+  schema: { input: GitHubPushInput, output: z.object({ ok: z.boolean() }) },
+  handler: async (ctx, input) => {
+    return { ok: true };
+  },
+});
+```
+
+**For `mode: 'queue'`** — register a job:
+
+```ts
+export const ProcessGitHubIssueJob = {
+  name: 'github.processIssue',
+  schema: z.object({ action: z.string(), issue: z.object({ id: z.number() }) }),
+  retry: { attempts: 3, backoff: 'exponential' as const },
+  handler: async (data, ctx) => {
+    ctx.logger.info({ issueId: data.issue.id }, 'Processing GitHub issue');
+  },
+};
+```
+
+---
+
+## When to Use Direct vs Queue
+
+| | Direct (`mode: 'direct'`) | Queue (`mode: 'queue'`) |
+|-|---------------------------|-------------------------|
+| **Use when** | Response must be synchronous | Processing is slow or can be retried |
+| **Backed by** | `communication.call()` | `jobQueue.enqueue()` (BullMQ/Redis) |
+| **Retries** | No built-in retry | BullMQ retry with backoff |
+
+---
+
+## Checklist
+
+- [ ] Auth controller created (extends `ApiKeyAuthController` or `OAuthAuthController`)
+- [ ] Webhook controller created with `prefix`, `auth`, and routes in `init()`
+- [ ] Routes configured with correct `mode`, `procedure`/`jobName`, and optional `ttl`
+- [ ] Controller registered on `WebhookServer`
+- [ ] Communication handler or job registered for each route
+- [ ] Webhook secret stored via `@mariachi/config` (never hardcoded)

package/docs/recipes/wiring-and-bootstrap.md

@@ -0,0 +1,250 @@
+# Recipe: Wiring and Bootstrap
+
+This shows the full initialization sequence for a Mariachi application — from loading config to accepting requests. Understanding the wiring order is critical because components depend on each other: communication handlers must be registered before controllers call them, and infrastructure (DB, Redis) must connect before services that use them.
+
+---
+
+## Initialization Order
+
+```
+1. Load config              loadConfig() or bootstrap()
+2. Create observability     createObservability() → logger, tracer, metrics
+3. Register in container    container.register(KEYS.Logger, logger) etc.
+4. Create infrastructure   createPostgresDatabase(), createCache(), createEventBus()
+5. Register infra in DI     container.register(KEYS.Database, db) etc.
+6. Create communication     createCommunication()
+7. Register handlers        registerServiceHandlers(communication)
+8. Create servers           new FastifyAdapter() with auth + rate limiting
+9. Register controllers     server.registerController(new XxxController())
+10. Connect infra           startup hooks: db.connect(), cache.connect()
+11. Start servers           server.listen(port)
+```
+
+Steps 6-7 must happen before 8-9. If a controller calls `communication.call('users.create', ...)` but no handler is registered for `users.create`, it will fail at runtime.
+
+---
+
+## Minimal Bootstrap
+
+The simplest wiring uses `bootstrap()` from `@mariachi/lifecycle`, which handles steps 1-3:
+
+```ts
+import { bootstrap } from '@mariachi/lifecycle';
+import { createCommunication } from '@mariachi/communication';
+import { registerServiceHandlers } from './services';
+import { FastifyAdapter } from '@mariachi/api-facade';
+import { UsersController } from './controllers/users.controller';
+
+async function main() {
+  const { logger, startup, shutdown } = bootstrap();
+
+  const communication = createCommunication();
+  registerServiceHandlers(communication);
+
+  const server = new FastifyAdapter({ name: 'public' })
+    .withAuth(['session', 'api-key'])
+    .withRateLimit({ perUser: 1000, perApiKey: 5000, window: '1h' });
+
+  server.registerController(new UsersController());
+
+  startup.register({
+    name: 'server',
+    priority: 100,
+    fn: async () => {
+      await server.listen(3000);
+      logger.info({ port: 3000 }, 'Server started');
+    },
+  });
+
+  shutdown.register({
+    name: 'server',
+    priority: 100,
+    fn: () => server.close(),
+  });
+
+  await startup.runAll(logger);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+```
+
+---
+
+## Full Bootstrap (with all infrastructure)
+
+For a production app that needs database, cache, events, auth, and billing:
+
+```ts
+import { getContainer, KEYS } from '@mariachi/core';
+import { loadConfig } from '@mariachi/config';
+import { createObservability } from '@mariachi/observability';
+import { bootstrap } from '@mariachi/lifecycle';
+import { createPostgresDatabase } from '@mariachi/database-postgres';
+import { createCache } from '@mariachi/cache';
+import { createEventBus } from '@mariachi/events';
+import { createAuth } from '@mariachi/auth';
+import { createRateLimiter } from '@mariachi/rate-limit';
+import { createCommunication } from '@mariachi/communication';
+
+async function main() {
+  const config = loadConfig();
+
+  const { logger, tracer, metrics } = createObservability({
+    logging: { adapter: 'pino', level: 'info' },
+  });
+
+  const container = getContainer();
+  container.register(KEYS.Config, config);
+  container.register(KEYS.Logger, logger);
+  container.register(KEYS.Tracer, tracer);
+  container.register(KEYS.Metrics, metrics);
+
+  const db = createPostgresDatabase({ url: config.database.url });
+  container.register(KEYS.Database, db);
+
+  const cache = createCache({ adapter: 'redis', url: config.redis!.url });
+  container.register(KEYS.Cache, cache);
+
+  const events = createEventBus({ adapter: 'redis', url: config.redis!.url });
+  container.register(KEYS.EventBus, events);
+
+  const auth = createAuth({ adapter: 'jwt', jwtSecret: config.auth!.jwtSecret! });
+  container.register(KEYS.Auth, auth);
+
+  const rateLimiter = createRateLimiter({ adapter: 'redis', url: config.redis!.url });
+  container.register(KEYS.RateLimit, rateLimiter);
+
+  const { startup, shutdown, health } = bootstrap();
+
+  const communication = createCommunication();
+  container.register(KEYS.Communication, communication);
+  registerServiceHandlers(communication);
+
+  const publicServer = new FastifyAdapter({ name: 'public' })
+    .withAuth(['session', 'api-key'])
+    .withRateLimit({ perUser: 1000, perApiKey: 5000, window: '1h' });
+
+  publicServer.registerController(new UsersController());
+  publicServer.registerController(new OrdersController());
+
+  startup.register({ name: 'database', priority: 1, fn: () => db.connect() });
+  startup.register({ name: 'cache', priority: 2, fn: () => cache.connect() });
+  startup.register({ name: 'events', priority: 3, fn: () => events.connect() });
+
+  startup.register({ name: 'servers', priority: 100, fn: async () => {
+    await publicServer.listen(3000);
+    logger.info({ port: 3000 }, 'Server started');
+  }});
+
+  shutdown.register({ name: 'servers', priority: 1, fn: () => publicServer.close() });
+  shutdown.register({ name: 'events', priority: 10, fn: () => events.disconnect() });
+  shutdown.register({ name: 'cache', priority: 20, fn: () => cache.disconnect() });
+  shutdown.register({ name: 'database', priority: 30, fn: () => db.disconnect() });
+
+  await startup.runAll(logger);
+}
+```
+
+---
+
+## Startup/Shutdown Priorities
+
+Hooks run in order of priority (lowest first). Convention:
+
+| Priority | Phase | What |
+|----------|-------|------|
+| 1-10 | Infrastructure | Database, cache, event bus connections |
+| 50 | Services | Communication handler registration, event subscribers |
+| 100 | Servers | HTTP server listen, WebSocket server start |
+
+For shutdown, use the inverse: stop servers first (priority 1), then services, then infrastructure.
+
+---
+
+## Worker Bootstrap
+
+Workers follow the same pattern but with job queues:
+
+```ts
+import { bootstrap } from '@mariachi/lifecycle';
+import { createJobQueue } from '@mariachi/jobs';
+import { SendEmailJob } from './jobs/send-email.job';
+import { schedules } from './jobs/schedules';
+
+const { config, logger, startup, shutdown } = bootstrap();
+
+const jobQueue = createJobQueue({
+  adapter: 'bullmq',
+  redisUrl: config.redis!.url,
+}, logger);
+
+jobQueue.registerJob(SendEmailJob);
+for (const schedule of schedules) {
+  jobQueue.register(schedule);
+}
+
+startup.register({
+  name: 'job-queue',
+  priority: 10,
+  fn: async () => {
+    await jobQueue.connect();
+    await jobQueue.start();
+  },
+});
+
+shutdown.register({
+  name: 'job-queue',
+  priority: 10,
+  fn: async () => {
+    await jobQueue.stop();
+    await jobQueue.disconnect();
+  },
+});
+
+startup.runAll(logger).catch((err) => {
+  logger.error({ err }, 'Worker failed to start');
+  process.exit(1);
+});
+```
+
+---
+
+## DI Container Keys
+
+All well-known keys are defined in `@mariachi/core`:
+
+```ts
+import { KEYS } from '@mariachi/core';
+
+KEYS.Config          // AppConfig
+KEYS.Logger          // Logger
+KEYS.Tracer          // TracerAdapter
+KEYS.Metrics         // MetricsAdapter
+KEYS.Database        // Database / PostgresAdapter
+KEYS.Cache           // Cache / CacheClient
+KEYS.EventBus        // EventBus
+KEYS.JobQueue        // JobQueue
+KEYS.Auth            // Auth
+KEYS.Communication   // CommunicationLayer
+// ... and others
+```
+
+Services that extend `Instrumentable` automatically resolve `Logger`, `Tracer`, and `Metrics` from the container.
+
+---
+
+## Checklist
+
+- [ ] Config loaded and validated
+- [ ] Logger + tracer + metrics created and registered in container
+- [ ] Infrastructure created (DB, cache, events) and registered in container
+- [ ] Communication layer created
+- [ ] Service handlers registered on communication layer
+- [ ] Servers created with auth and rate limiting
+- [ ] Controllers registered on servers
+- [ ] Startup hooks registered (infra connect at low priority, servers at high priority)
+- [ ] Shutdown hooks registered (reverse order)
+- [ ] `startup.runAll(logger)` called

package/docs/runbook.md

@@ -0,0 +1,84 @@
+# Mariachi Runbook
+
+Operational guide for developing and running Mariachi applications.
+
+## Prerequisites
+
+- **Node.js** ≥ 20
+- **pnpm** (package manager)
+
+## Getting Started
+
+```bash
+pnpm install
+pnpm run build
+pnpm run dev
+```
+
+## Running Tests
+
+```bash
+pnpm run test
+```
+
+For a single run (CI):
+
+```bash
+pnpm run test:run
+```
+
+## Adding a New Service
+
+Generate a service with handlers and tests (if using `@mariachi/cli`):
+
+```bash
+mariachi generate service <name>
+```
+
+Example:
+
+```bash
+mariachi generate service orders
+```
+
+Creates a domain folder with `orders.service.ts`, `orders.handler.ts`, and tests.
+
+## Adding a New Integration
+
+Generate an integration scaffold (if using `@mariachi/cli`):
+
+```bash
+mariachi generate integration <name>
+```
+
+## Validating
+
+Validate project structure and conventions (if using `@mariachi/cli`):
+
+```bash
+mariachi validate
+```
+
+Optionally specify a path:
+
+```bash
+mariachi validate ./apps
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NODE_ENV` / `ENV` | Environment (`development`, `test`, `production`) | — |
+| `PORT` | Public API port | `3000` |
+| `ADMIN_PORT` | Admin API port | `3001` |
+| `WEBHOOK_PORT` | Webhook server port | `3002` |
+| `DATABASE_URL` | PostgreSQL connection string | — |
+| `DATABASE_ADAPTER` | Database adapter | `postgres` |
+| `DATABASE_POOL_MIN` | Connection pool minimum | `2` |
+| `DATABASE_POOL_MAX` | Connection pool maximum | `10` |
+| `REDIS_URL` | Redis connection string | — |
+| `JWT_SECRET` | JWT signing secret | — |
+| `SESSION_SECRET` | Session secret (fallback for JWT) | — |
+
+Configuration is loaded via `@mariachi/config`; avoid using `process.env` directly outside that package.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mariachi/core",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    ".mariachi",
+    ".cursor"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^3.24"
+  },
+  "devDependencies": {
+    "typescript": "^5.7",
+    "tsup": "^8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}