@mariachi/core 0.0.1

package/docs/patterns.md

@@ -0,0 +1,71 @@
+# Mariachi Core Patterns
+
+## 1. Adapter Factory
+
+Every external dependency is behind an adapter. A factory function selects the implementation from config.
+
+```ts
+const cache = createCache({ adapter: 'redis', url: process.env.REDIS_URL });
+const search = createSearch({ adapter: 'typesense', ... });
+const jobQueue = createJobQueue({ adapter: 'bullmq', redisUrl: ... }, logger);
+```
+
+Production adapters: Redis, PostgreSQL, Stripe, Typesense, BullMQ, Resend, S3, OpenAI.
+Test doubles live in `@mariachi/testing` (e.g. `TestCacheClient`, `TestEventBus`).
+
+## 2. Abstract Service Class
+
+Each package exposes: `X` (abstract) → `DefaultX extends X`. The abstract class layers observability, error handling, and hooks on top of raw adapters.
+
+```ts
+export abstract class Notifications implements Instrumentable { ... }
+export class DefaultNotifications extends Notifications { ... }
+```
+
+Subclass `DefaultX` when custom behavior is needed.
+
+## 3. Instrumentable & Disposable
+
+Two interfaces from `@mariachi/core` that every service implements:
+
+- **Instrumentable**: `{ logger, tracer?, metrics? }` — pulled from the DI container
+- **Disposable**: `{ connect(), disconnect(), isHealthy() }` — lifecycle management
+
+## 4. DI Container
+
+Global container via `getContainer()` with well-known `KEYS`:
+
+```ts
+import { getContainer, KEYS } from '@mariachi/core';
+const container = getContainer();
+container.register(KEYS.Logger, logger);
+const logger = container.resolve<Logger>(KEYS.Logger);
+```
+
+`bootstrap()` registers `Config` and `Logger` automatically. Other services register themselves as needed.
+
+## 5. Context Propagation
+
+Every operation receives a `Context` carrying identity and tracing:
+
+```ts
+interface Context {
+  traceId: string;
+  userId: string | null;
+  tenantId: string | null;
+  scopes: string[];
+  identityType: string;
+  logger: Logger;
+}
+```
+
+Never lose context between layers. Pass `ctx` through communication calls, service methods, and event handlers.
+
+## 6. Zod Schemas at Boundaries
+
+Validate at entry points, not deep in business logic:
+
+- **Controller**: parse request body with Zod before calling communication
+- **Handler registration**: declare `schema: { input, output }` with Zod schemas
+- **Job definition**: declare `schema` for job payload
+- **Config**: `AppConfigSchema` validates all configuration at load time

package/docs/recipes/add-background-job.md

@@ -0,0 +1,156 @@
+# Recipe: Add a Background Job
+
+This walks through defining a new job, registering it in the worker, and enqueuing it from a service.
+
+---
+
+## 1. Define the Job
+
+Jobs are plain objects with `name`, `schema` (Zod), `retry` config, and a `handler`.
+
+**File:** e.g. `src/jobs/process-order.job.ts`
+
+```ts
+import { z } from 'zod';
+
+export const ProcessOrderJob = {
+  name: 'orders.process',
+  schema: z.object({
+    orderId: z.string(),
+    userId: z.string(),
+  }),
+  retry: { attempts: 3, backoff: 'exponential' as const },
+  handler: async (
+    data: { orderId: string; userId: string },
+    ctx: { logger: any; traceId: string; attemptNumber: number; jobId: string },
+  ) => {
+    ctx.logger.info({ orderId: data.orderId }, 'Processing order');
+    // business logic here
+  },
+};
+```
+
+**Job handler signature:**
+- `data` — validated payload (matches the Zod schema)
+- `ctx` — job context with `logger`, `traceId`, `attemptNumber`, `jobId`
+
+**Retry options:**
+- `attempts` — max retries
+- `backoff` — `'exponential'` or `'fixed'`
+
+---
+
+## 2. Register the Job in the Worker
+
+Add the job to the worker entry point.
+
+**File:** e.g. `src/worker/index.ts`
+
+```ts
+import { ProcessOrderJob } from './jobs/process-order.job';
+
+jobQueue.registerJob(ProcessOrderJob);
+```
+
+---
+
+## 3. Add a Schedule (Optional)
+
+If the job should run on a cron schedule, add an entry to your schedules.
+
+**File:** e.g. `src/jobs/schedules.ts`
+
+```ts
+export const schedules = [
+  { name: 'daily-cleanup', cron: '0 0 * * *', jobName: 'system.cleanup', data: {} },
+  { name: 'hourly-order-check', cron: '0 * * * *', jobName: 'orders.process', data: { orderId: 'batch', userId: 'system' } },
+];
+```
+
+Register in the worker entry:
+
+```ts
+for (const schedule of schedules) {
+  jobQueue.register(schedule);
+}
+```
+
+---
+
+## 4. Enqueue from a Service
+
+To trigger a job from business logic, use `jobQueue.enqueue()`.
+
+```ts
+import { createJobQueue } from '@mariachi/jobs';
+
+const jobQueue = createJobQueue({ adapter: 'bullmq', redisUrl: config.redis.url }, logger);
+
+await jobQueue.enqueue('orders.process', { orderId: '123', userId: 'user-1' });
+```
+
+For deduplication (prevent duplicate jobs for the same entity):
+
+```ts
+await jobQueue.enqueueWithDedup('orders.process', { orderId: '123', userId: 'user-1' }, {
+  dedupKey: 'orders.process:123',
+});
+```
+
+---
+
+## 5. Test the Job
+
+Use `TestJobQueue` from `@mariachi/testing`:
+
+```ts
+import { describe, it, expect } from 'vitest';
+import { TestJobQueue } from '@mariachi/testing';
+import { ProcessOrderJob } from '../process-order.job';
+
+describe('ProcessOrderJob', () => {
+  it('processes an order', async () => {
+    const queue = new TestJobQueue();
+    queue.registerJob(ProcessOrderJob);
+    await queue.enqueue('orders.process', { orderId: '123', userId: 'user-1' });
+    expect(queue.jobs).toHaveLength(1);
+    expect(queue.jobs[0].name).toBe('orders.process');
+  });
+});
+```
+
+---
+
+## Worker Lifecycle
+
+The worker connects to Redis (BullMQ) on startup and gracefully stops on shutdown:
+
+```ts
+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();
+  },
+});
+```
+
+---
+
+## Checklist
+
+- [ ] Job defined with Zod schema and retry config
+- [ ] Job registered via `jobQueue.registerJob()` in worker entry point
+- [ ] Schedule added (if cron-based)
+- [ ] Enqueue call added in the service that triggers the job
+- [ ] Tests added using `TestJobQueue`

package/docs/recipes/add-domain-entity.md

@@ -0,0 +1,248 @@
+# Recipe: Add a Domain Entity End-to-End
+
+This walks through adding a new domain (e.g. `orders`) from schema to API endpoint. Each step references real patterns from the existing `users` domain.
+
+---
+
+## 1. Define the Schema
+
+Create the table definition in `@mariachi/database`.
+
+**File:** (in your app or shared package) e.g. `src/schema/orders.ts`
+
+```ts
+import { defineTable } from '@mariachi/database';
+import { column } from '@mariachi/database';
+
+export const ordersTable = defineTable('orders', {
+  id:        column.uuid().primaryKey().defaultRandom(),
+  tenantId:  column.text().notNull(),
+  userId:    column.text().notNull(),
+  total:     column.numeric().notNull(),
+  status:    column.text().notNull(),
+  createdAt: column.timestamp().notNull().defaultNow(),
+  updatedAt: column.timestamp().notNull().defaultNow(),
+  deletedAt: column.timestamp(),
+});
+```
+
+---
+
+## 2. Compile to Drizzle
+
+Add the compiled table for use with `@mariachi/database-postgres`.
+
+**File:** e.g. `src/compiled-schemas.ts`
+
+```ts
+import { ordersTable } from './schema/orders';
+import { compileTable } from '@mariachi/database-postgres';
+export const orders = compileTable(ordersTable);
+```
+
+---
+
+## 3. Create the Repository
+
+**File:** e.g. `src/repositories/orders.repository.ts`
+
+```ts
+import type { Context } from '@mariachi/core';
+import { DrizzleRepository } from '@mariachi/database-postgres';
+import { orders } from '../compiled-schemas';
+
+export interface Order {
+  id: string;
+  tenantId: string;
+  userId: string;
+  total: string;
+  status: string;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt: Date | null;
+}
+
+export class DrizzleOrdersRepository extends DrizzleRepository<Order> {
+  constructor(db: import('drizzle-orm/postgres-js').PostgresJsDatabase<Record<string, never>>) {
+    super(orders, db, { tenantColumn: 'tenantId' });
+  }
+
+  async findByUser(ctx: Context, userId: string): Promise<Order[]> {
+    return this.findMany(ctx, { userId } as Partial<Order>);
+  }
+}
+```
+
+Inherited from `DrizzleRepository`: `findById`, `findMany`, `create`, `update`, `softDelete`, `hardDelete`, `paginate`, `count`.
+
+---
+
+## 4. Create the Service
+
+**File:** e.g. `src/orders/orders.service.ts` (in your services app)
+
+```ts
+import type { Context } from '@mariachi/core';
+import { z } from 'zod';
+
+export const CreateOrderInput = z.object({
+  userId: z.string(),
+  total: z.string(),
+  status: z.string().default('pending'),
+  tenantId: z.string(),
+});
+
+export const GetOrderInput = z.object({
+  orderId: z.string(),
+});
+
+export const OrdersService = {
+  create: async (ctx: Context, input: z.infer<typeof CreateOrderInput>) => {
+    ctx.logger.info({ userId: input.userId }, 'Creating order');
+    const repo = new DrizzleOrdersRepository(db);
+    return repo.create(ctx, input);
+  },
+  getById: async (ctx: Context, input: z.infer<typeof GetOrderInput>) => {
+    ctx.logger.info({ orderId: input.orderId }, 'Fetching order');
+    const repo = new DrizzleOrdersRepository(db);
+    return repo.findById(ctx, input.orderId);
+  },
+};
+```
+
+---
+
+## 5. Register Communication Handlers
+
+**File:** e.g. `src/orders/orders.handler.ts`
+
+```ts
+import { OrdersService, CreateOrderInput, GetOrderInput } from './orders.service';
+import { z } from 'zod';
+
+const OrderOutput = z.object({
+  id: z.string(),
+  userId: z.string(),
+  total: z.string(),
+  status: z.string(),
+  tenantId: z.string(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+  deletedAt: z.date().nullable(),
+});
+
+export function registerOrdersHandlers(communication: ReturnType<typeof createCommunication>) {
+  communication.register('orders.create', {
+    schema: { input: CreateOrderInput, output: OrderOutput },
+    handler: (ctx, input) => OrdersService.create(ctx, input),
+  });
+  communication.register('orders.getById', {
+    schema: { input: GetOrderInput, output: OrderOutput.nullable() },
+    handler: (ctx, input) => OrdersService.getById(ctx, input),
+  });
+}
+```
+
+Wire into your aggregate registration (e.g. in your services app entry):
+
+```ts
+import { registerOrdersHandlers } from './orders/orders.handler';
+
+export function registerServiceHandlers(communication) {
+  registerUsersHandlers(communication);
+  registerOrdersHandlers(communication);
+}
+```
+
+---
+
+## 6. Add the Controller
+
+**File:** e.g. `src/controllers/orders.controller.ts` (in your API app)
+
+```ts
+import { z } from 'zod';
+import { BaseController, type HttpContext } from '@mariachi/api-facade';
+import { createCommunication } from '@mariachi/communication';
+
+const CreateOrderInput = z.object({
+  userId: z.string(),
+  total: z.string(),
+  status: z.string().optional(),
+});
+
+const GetOrderParams = z.object({
+  orderId: z.string(),
+});
+
+const communication = createCommunication();
+
+export class OrdersController extends BaseController {
+  readonly prefix = 'orders';
+
+  init() {
+    this.post(this.buildPath(), this.create);
+    this.get(this.buildPath(':id'), this.getById);
+  }
+
+  create = async (ctx: HttpContext, body: unknown) => {
+    const input = CreateOrderInput.parse(body);
+    return communication.call('orders.create', ctx, input);
+  };
+
+  getById = async (ctx: HttpContext, _body: unknown, params: Record<string, string>) => {
+    const input = GetOrderParams.parse({ orderId: params.id });
+    return communication.call('orders.getById', ctx, input);
+  };
+}
+```
+
+Register on your server:
+
+```ts
+import { OrdersController } from './controllers/orders.controller';
+
+const publicServer = createPublicServer()
+  .registerController(new UsersController())
+  .registerController(new OrdersController());
+```
+
+---
+
+## 7. Add Tests
+
+**File:** e.g. `src/orders/test/orders.service.test.ts`
+
+```ts
+import { describe, it, expect } from 'vitest';
+import { createTestContext } from '@mariachi/testing';
+import { OrdersService } from '../orders.service';
+
+describe('OrdersService', () => {
+  it('creates an order', async () => {
+    const ctx = createTestContext();
+    const result = await OrdersService.create(ctx, {
+      userId: 'user-1',
+      total: '99.99',
+      status: 'pending',
+      tenantId: 'tenant-1',
+    });
+    expect(result.id).toBeDefined();
+    expect(result.userId).toBe('user-1');
+  });
+});
+```
+
+---
+
+## Checklist
+
+- [ ] Schema defined and exported
+- [ ] Compiled table added for Drizzle
+- [ ] Repository created extending `DrizzleRepository`
+- [ ] Service created in services app
+- [ ] Handler registered via `communication.register()`
+- [ ] Handler wired into `registerServiceHandlers()`
+- [ ] Controller created in API app
+- [ ] Controller registered on server
+- [ ] Tests added

package/docs/recipes/add-integration.md

@@ -0,0 +1,198 @@
+# Recipe: Add a Third-Party Integration
+
+This walks through adding a new integration (e.g. GitHub, Twilio) using the `@mariachi/integrations` pattern.
+
+---
+
+## Structure
+
+```
+integrations/<name>/
+├── index.ts         # Integration functions (defineIntegrationFn)
+├── credentials.ts   # Zod-validated credential schema
+├── client.ts        # Raw API client (fetch calls)
+├── types.ts         # Input/output Zod schemas
+└── test.ts          # Dry-run test
+```
+
+---
+
+## 1. Define Credentials
+
+Every integration has a Zod schema for its credentials. Never hardcode secrets.
+
+**File:** `integrations/<name>/credentials.ts`
+
+```ts
+import { z } from 'zod';
+
+export const GitHubCredentials = z.object({
+  token: z.string().min(1),
+  webhookSecret: z.string().min(1),
+});
+
+export type GitHubCredentials = z.infer<typeof GitHubCredentials>;
+```
+
+Store actual values via `@mariachi/config` (env variables), not in code.
+
+---
+
+## 2. Define Input/Output Types
+
+Use Zod schemas for all inputs and outputs.
+
+**File:** `integrations/<name>/types.ts`
+
+```ts
+import { z } from 'zod';
+
+export const CreateIssueInput = z.object({
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+  title: z.string().min(1),
+  body: z.string().optional(),
+});
+
+export const CreateIssueOutput = z.object({
+  id: z.number(),
+  number: z.number(),
+  url: z.string(),
+});
+
+export type CreateIssueInput = z.infer<typeof CreateIssueInput>;
+export type CreateIssueOutput = z.infer<typeof CreateIssueOutput>;
+```
+
+---
+
+## 3. Implement the Client
+
+The client is a thin wrapper around the external API.
+
+**File:** `integrations/<name>/client.ts`
+
+```ts
+import type { GitHubCredentials } from './credentials';
+import type { CreateIssueInput, CreateIssueOutput } from './types';
+
+export async function createIssue(
+  credentials: GitHubCredentials,
+  input: CreateIssueInput,
+): Promise<CreateIssueOutput> {
+  const url = `https://api.github.com/repos/${input.owner}/${input.repo}/issues`;
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${credentials.token}`,
+      Accept: 'application/vnd.github+json',
+    },
+    body: JSON.stringify({ title: input.title, body: input.body }),
+  });
+
+  if (!res.ok) {
+    throw new Error(`GitHub API error: ${res.status} ${await res.text()}`);
+  }
+
+  const data = (await res.json()) as { id: number; number: number; html_url: string };
+  return { id: data.id, number: data.number, url: data.html_url };
+}
+```
+
+---
+
+## 4. Define the Integration Function
+
+Use `defineIntegrationFn` from `@mariachi/integrations`.
+
+**File:** `integrations/<name>/index.ts`
+
+```ts
+import { defineIntegrationFn } from '@mariachi/integrations';
+import type { IntegrationContext } from '@mariachi/integrations';
+import { createIssue } from './client';
+import type { GitHubCredentials } from './credentials';
+import { CreateIssueInput, CreateIssueOutput } from './types';
+
+export interface GitHubIntegrationContext extends IntegrationContext {
+  credentials: GitHubCredentials;
+}
+
+export const githubCreateIssue = defineIntegrationFn<CreateIssueInput, CreateIssueOutput>({
+  name: 'github.createIssue',
+  input: CreateIssueInput,
+  output: CreateIssueOutput,
+  handler: async (input: CreateIssueInput, ctx: IntegrationContext): Promise<CreateIssueOutput> => {
+    const credentials = (ctx as GitHubIntegrationContext).credentials;
+    if (!credentials) {
+      throw new Error('GitHub credentials required');
+    }
+    return createIssue(credentials, input);
+  },
+  retry: { attempts: 3, backoff: 'exponential' },
+});
+```
+
+**Key fields:**
+- `name` — unique identifier, conventionally `<provider>.<action>`
+- `input` / `output` — Zod schemas for validation
+- `handler` — receives validated input and `IntegrationContext` (with credentials)
+- `retry` — optional retry config
+
+---
+
+## 5. Register in the Registry (Optional)
+
+For discoverability, register the integration in a central registry.
+
+```ts
+import { IntegrationRegistry } from '@mariachi/integrations';
+import { GitHubCredentials } from './credentials';
+
+const registry = new IntegrationRegistry();
+registry.register({
+  name: 'github',
+  description: 'GitHub integration for issues and repositories',
+  credentialSchema: GitHubCredentials,
+  functions: ['github.createIssue'],
+});
+```
+
+---
+
+## 6. Add a Test
+
+**File:** `integrations/<name>/test.ts`
+
+```ts
+import { CreateIssueInput } from './types';
+import { GitHubCredentials } from './credentials';
+
+export async function dryRun(
+  credentials: GitHubCredentials,
+  input: { owner: string; repo: string; title: string; body?: string },
+): Promise<{ ok: true; id: number; number: number; url: string }> {
+  GitHubCredentials.parse(credentials);
+  CreateIssueInput.parse(input);
+  return {
+    ok: true,
+    id: 12345,
+    number: 1,
+    url: `https://github.com/${input.owner}/${input.repo}/issues/1`,
+  };
+}
+```
+
+---
+
+## Checklist
+
+- [ ] Credentials schema defined in `credentials.ts` (Zod)
+- [ ] Input/output types defined in `types.ts` (Zod)
+- [ ] Client function implemented in `client.ts`
+- [ ] Integration function defined with `defineIntegrationFn` in `index.ts`
+- [ ] Retry config set appropriately
+- [ ] Dry-run test in `test.ts`
+- [ ] Secrets stored via env/config, never hardcoded