@mariachi/core 0.0.1

package/.cursor/rules/mariachi.mdc

@@ -0,0 +1,36 @@
+---
+description: Mariachi framework conventions and patterns. Use when building with @mariachi/* packages. Read the docs in this package before writing code.
+alwaysApply: false
+---
+
+# Mariachi Framework (consumer)
+
+When working in a project that uses Mariachi, read these files from the installed package:
+
+**Quick reference (same content as root `.mariachi/` in the framework repo):**
+
+- `node_modules/@mariachi/core/.mariachi/architecture.md` — Three-layer architecture (Facade → Controller → Service), import boundaries, naming conventions
+- `node_modules/@mariachi/core/.mariachi/conventions.md` — TypeScript/ESM rules, dependency rules, error handling, anti-patterns
+- `node_modules/@mariachi/core/.mariachi/packages.md` — All 28 packages with when to use each one
+- `node_modules/@mariachi/core/.mariachi/patterns.md` — Adapter factory, abstract service class, DI container, context propagation, Zod at boundaries
+
+**Step-by-step recipes:**
+
+- `node_modules/@mariachi/core/docs/recipes/add-domain-entity.md` — Schema, repository, service, handler, controller, tests
+- `node_modules/@mariachi/core/docs/recipes/add-background-job.md` — Job definition, worker registration, scheduling
+- `node_modules/@mariachi/core/docs/recipes/add-webhook-endpoint.md` — WebhookController with direct/queue modes
+- `node_modules/@mariachi/core/docs/recipes/add-integration.md` — Third-party integration with credentials and retry
+- `node_modules/@mariachi/core/docs/recipes/wiring-and-bootstrap.md` — Full initialization order from config to running servers
+
+**Decision trees and gotchas:** `node_modules/@mariachi/core/docs/ai-guide.md`
+
+## Critical Rules
+
+- Relative imports are extensionless: `import { foo } from './bar'` (not `'./bar.js'`)
+- Controllers never import services — always use `communication.call()`
+- Every operation takes `Context` as first argument — never drop context
+- Throw typed errors (`MariachiError` subclasses), never raw `Error`
+- Use factory functions (`createCache`, `createSearch`), never instantiate adapters directly
+- Validate with Zod at boundaries (controller input, handler schemas, job payloads)
+
+**To use this rule in Cursor:** Copy this file to your project's `.cursor/rules/` (e.g. `.cursor/rules/mariachi.mdc`) so Cursor picks it up. Paths above are relative to your project root where `node_modules/@mariachi/core` is installed.

package/.mariachi/architecture.md

@@ -0,0 +1,46 @@
+# Mariachi Architecture
+
+## Three-Layer Request Flow
+
+```
+HTTP Request → Facade → Controller → Communication Layer → Service
+```
+
+| Layer | Location | Responsibility |
+|-------|----------|----------------|
+| **Facade** | Your API app (e.g. `src/servers/`) | Fastify server, auth strategies, rate limiting |
+| **Controller** | Your API app (e.g. `src/controllers/`) | Parse/validate input (Zod), call `communication.call()` |
+| **Service** | Your services app (e.g. `src/<domain>/`) | Business logic, DB, cache, events, jobs |
+
+## Import Boundaries
+
+- **Controllers** may import: `@mariachi/api-facade`, `@mariachi/communication`, `zod`
+- **Services** may import: any `@mariachi/*` package
+- **Controllers never import services directly** — always go through the communication layer
+
+## Project Structure
+
+Organize your app in three layers:
+
+- **API app** — HTTP servers + controllers (Facade + Controller layers)
+- **Services app** — Domain services + communication handlers (Service layer)
+- **Worker app** — BullMQ job workers and schedules
+
+## Naming Conventions
+
+| Artifact | Convention | Example |
+|----------|-----------|---------|
+| Controller | `<Domain>Controller` in `<domain>.controller.ts` | `UsersController` |
+| Service | `<Domain>Service` object in `<domain>.service.ts` | `UsersService` |
+| Handler | `register<Domain>Handlers` in `<domain>.handler.ts` | `registerUsersHandlers` |
+| Job | `<Action>Job` object in `<action>.job.ts` | `SendEmailJob` |
+| Schema table | `<domain>Table` via `defineTable` | `usersTable` |
+| Repository | `Drizzle<Domain>Repository` | `DrizzleUsersRepository` |
+| Procedure name | `<domain>.<action>` | `users.create` |
+
+## Key Entry Points
+
+- `bootstrap()` from `@mariachi/lifecycle` — loads config, creates observability, sets up DI container
+- `createCommunication()` from `@mariachi/communication` — returns in-process communication layer
+- `FastifyAdapter` from `@mariachi/api-facade` — builds HTTP server with auth and rate limiting
+- Register your domain handlers with the communication layer so controllers can call them via `communication.call('<domain>.<action>', ctx, input)`

package/.mariachi/conventions.md

@@ -0,0 +1,109 @@
+# Mariachi Conventions
+
+## TypeScript and ESM
+
+- **All packages use ESM** (`"type": "module"` in every `package.json`)
+- **Build tool:** tsup (ESM + CJS dual output, declaration files, sourcemaps)
+- **TypeScript:** strict mode, ES2022 target, `"moduleResolution": "bundler"`
+- **Relative imports are extensionless:** `import { foo } from './bar'` (not `'./bar.js'`). The `"moduleResolution": "bundler"` tsconfig setting and tsup handle resolution.
+- **Cross-package imports use bare specifiers:** `import { Context } from '@mariachi/core'` (no extension)
+- **All packages export from `src/index.ts`** as the single public entry point
+
+### tsup Config (every package)
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  splitting: false,
+});
+```
+
+### tsconfig (every package)
+
+Extend a shared base or use standard options. No additional compiler options needed unless the package has special requirements.
+
+## File Organization
+
+- One file per concern: `types.ts`, `schema.ts`, `adapter.ts`, `middleware.ts`
+- Adapters go in `src/adapters/` subdirectory
+- Middleware goes in `src/middleware/` subdirectory
+- Schema definitions go in `src/schema/` subdirectory
+- Tests go alongside source in `test/` or `__tests__/` subdirectory
+
+## Dependency Rules
+
+- `@mariachi/core` has zero internal dependencies (only `zod`)
+- Other packages may depend on `@mariachi/core` freely
+- Packages should depend on abstractions, not implementations (e.g., depend on `@mariachi/database`, not `@mariachi/database-postgres`)
+- Apps may depend on any package
+- Circular dependencies between packages are not allowed
+
+## Error Handling
+
+- Always throw typed errors extending `MariachiError` from `@mariachi/core`
+- Each package has its own error class: `DatabaseError`, `AuthError`, `CacheError`, etc.
+- Never throw raw `Error` or string exceptions across package boundaries
+- Errors map to HTTP status codes via `errorToHttpStatus()` in the API facade layer
+
+## Anti-Patterns (Do Not Do These)
+
+**Do not import services from controllers.**
+Controllers must only call `communication.call()`. Never import a service or its handler directly.
+
+```ts
+// WRONG
+import { UsersService } from '../../services/users/users.service';
+const result = await UsersService.create(ctx, input);
+
+// CORRECT
+const result = await communication.call('users.create', ctx, input);
+```
+
+**Do not use `process.env` outside `@mariachi/config`.**
+All configuration flows through `loadConfig()` and `useConfig()`. Direct env access scatters configuration and bypasses validation.
+
+```ts
+// WRONG
+const dbUrl = process.env.DATABASE_URL;
+
+// CORRECT
+const config = useConfig();
+const dbUrl = config.database.url;
+```
+
+Exception: `PORT`, `ADMIN_PORT`, `WEBHOOK_PORT` in app entry points are acceptable since they're startup-only values.
+
+**Do not skip context propagation.**
+Every operation takes a `Context` as its first argument. Never create a new context mid-flow or drop context between layers.
+
+```ts
+// WRONG
+const user = await UsersService.create({ email, name });
+
+// CORRECT
+const user = await UsersService.create(ctx, { email, name });
+```
+
+**Do not expose the Drizzle client directly.**
+All database access goes through repository classes that extend `DrizzleRepository`. The ORM is an implementation detail.
+
+**Do not hardcode adapter choices.**
+Use factory functions (`createCache`, `createSearch`, `createJobQueue`) with config. Never instantiate adapters directly in application code.
+
+```ts
+// WRONG
+const cache = new RedisCacheAdapter({ url: 'redis://localhost' });
+
+// CORRECT
+const cache = createCache({ adapter: 'redis', url: config.redis.url });
+```
+
+**Do not write migration files by hand.**
+Schema changes go through the `defineTable` DSL in `@mariachi/database`. Migrations are generated by `drizzle-kit`.
+
+**Do not register the same procedure name twice.**
+Communication procedure names (`users.create`, `billing.charge`, etc.) must be globally unique. Duplicate registrations will silently overwrite each other.

package/.mariachi/packages.md

@@ -0,0 +1,66 @@
+# Mariachi Packages
+
+Quick reference for all 28 packages. Use this to decide which package to reach for.
+
+## Foundation
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/core` | Types, errors, context, DI container, `Result<T,E>` | `getContainer()`, `createContext()`, `KEYS` |
+| `@mariachi/config` | Typed config from env, secrets, feature flags | `loadConfig()`, `useConfig()` |
+| `@mariachi/observability` | Logging, tracing, metrics, error tracking | `createObservability(config)` |
+| `@mariachi/lifecycle` | App bootstrap, startup/shutdown hooks, health checks | `bootstrap()` |
+
+## Communication & API
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/communication` | Inter-module procedure calls with middleware | `createCommunication()` |
+| `@mariachi/api-facade` | HTTP servers with auth, rate limiting, controllers | `new FastifyAdapter()`, `BaseController` |
+| `@mariachi/server` | Low-level Fastify adapter (used by api-facade) | `FastifyServerAdapter` |
+| `@mariachi/webhooks` | Inbound webhook endpoints with auth and logging | `WebhookController`, `WebhookServer` |
+
+## Data & Storage
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/database` | Schema definitions, repository interface, types | `defineTable()`, `column`, `Database` |
+| `@mariachi/database-postgres` | PostgreSQL + Drizzle ORM implementation | `createPostgresDatabase()`, `DrizzleRepository` |
+| `@mariachi/cache` | Redis caching, distributed locks, memoization | `createCache()`, `createLock()` |
+| `@mariachi/storage` | File/object storage (S3, local) | `Storage`, `DefaultStorage` |
+
+## Async & Events
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/events` | Pub/sub event bus (Redis or NATS) | `createEventBus()` |
+| `@mariachi/jobs` | Background job queue and scheduling (BullMQ) | `createJobQueue()`, `defineJob` |
+| `@mariachi/realtime` | WebSocket connections, channels, broadcasting | `Realtime`, `WSAdapter` |
+
+## Security & Access
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/auth` | JWT, API keys, OAuth, RBAC | `createAuth()`, `createAuthorization()` |
+| `@mariachi/auth-clerk` | Clerk authentication, webhook verification (Svix) | `createClerkAuth()`, `ClerkWebhookController` |
+| `@mariachi/tenancy` | Multi-tenant isolation (subdomain, header, JWT) | `createTenantResolver()`, `createTenancyMiddleware()` |
+| `@mariachi/rate-limit` | Redis sliding-window rate limiting | `createRateLimiter()` |
+
+## Domain Features
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/billing` | Stripe payments, subscriptions, credits, webhooks | `createBilling()`, `StripeAdapter` |
+| `@mariachi/notifications` | Email (Resend), SMS, push, in-app notifications | `Notifications`, `createEmailAdapter()` |
+| `@mariachi/search` | Full-text search (Typesense) | `createSearch()` |
+| `@mariachi/ai` | AI/LLM sessions, tools, prompts, agent loops | `createAI()`, `runAgent()` |
+| `@mariachi/audit` | Append-only audit logging | `createAuditLogger()` |
+| `@mariachi/integrations` | Third-party integration pattern | `defineIntegrationFn()` |
+
+## Tooling
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/testing` | In-memory test doubles, factories | `createTestHarness()`, `TestRepository` |
+| `@mariachi/create` | Code scaffolding and validation rules | `mariachi generate` |
+| `@mariachi/cli` | CLI binary | `mariachi init/generate/validate` |

package/.mariachi/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/README.md

@@ -0,0 +1,42 @@
+# @mariachi/core
+
+Shared types, typed errors, `Context`, DI container, `Result<T,E>`, and retry utilities for the Mariachi framework.
+
+## Framework documentation
+
+When you install any `@mariachi/*` package, this documentation is included so you don't lose the framework's conventions and recipes.
+
+### Quick reference (same as repo `.mariachi/`)
+
+- **[.mariachi/architecture.md](./.mariachi/architecture.md)** — Three-layer flow, import boundaries, naming
+- **[.mariachi/conventions.md](./.mariachi/conventions.md)** — TypeScript/ESM, dependency rules, anti-patterns
+- **[.mariachi/packages.md](./.mariachi/packages.md)** — All 28 packages and when to use each
+- **[.mariachi/patterns.md](./.mariachi/patterns.md)** — Adapter factory, DI container, context, Zod at boundaries
+
+### Full docs
+
+- **[docs/architecture.md](./docs/architecture.md)** — Architecture with mermaid diagrams, package overview, adapter pattern
+- **[docs/conventions.md](./docs/conventions.md)** — Same as .mariachi with full detail
+- **[docs/packages.md](./docs/packages.md)** — Same as .mariachi
+- **[docs/patterns.md](./docs/patterns.md)** — Same as .mariachi
+- **[docs/integrations.md](./docs/integrations.md)** — How to add third-party integrations
+- **[docs/ai-guide.md](./docs/ai-guide.md)** — Decision trees, package cheat sheet, common gotchas
+- **[docs/runbook.md](./docs/runbook.md)** — Environment variables, CLI commands, validation
+- **[docs/adr/001-adapter-pattern.md](./docs/adr/001-adapter-pattern.md)** — ADR: adapter pattern
+- **[docs/improvements/](./docs/improvements/)** — Draft improvements (e.g. notifications/realtime/NATS)
+
+### Step-by-step recipes
+
+- [docs/recipes/add-domain-entity.md](./docs/recipes/add-domain-entity.md) — Schema, repository, service, handler, controller, tests
+- [docs/recipes/add-background-job.md](./docs/recipes/add-background-job.md) — Job definition, worker registration, scheduling
+- [docs/recipes/add-webhook-endpoint.md](./docs/recipes/add-webhook-endpoint.md) — WebhookController with direct/queue modes
+- [docs/recipes/add-integration.md](./docs/recipes/add-integration.md) — Third-party integration with credentials and retry
+- [docs/recipes/wiring-and-bootstrap.md](./docs/recipes/wiring-and-bootstrap.md) — Full initialization order from config to running servers
+
+### Cursor / AI assistants
+
+A Cursor rule file is included so your IDE can use the framework conventions:
+
+- **Copy** `node_modules/@mariachi/core/.cursor/rules/mariachi.mdc` into your project's `.cursor/rules/` (e.g. as `mariachi.mdc`). The rule points the AI at the docs in this package.
+
+After `pnpm add @mariachi/core`, all of the above paths are available under `node_modules/@mariachi/core/`.