# `@x12i/catalox-engine`

The **Catalox catalog engine**: runtime API, Firestore/Mongo persistence, operator helpers, mapping module, and the **`catalox` CLI** binary.

Part of the [Catalox monorepo](../../README.md). Published on npm as a workspace package; consumers often install the root [`@x12i/catalox`](../../README.md) meta package instead.

---

## Role

| Responsibility | Details |
|----------------|---------|
| **Runtime** | `createCatalox`, `Catalox`, `CataloxBound` — list/get/write catalogs and items |
| **Persistence** | Firestore stores (default), Mongo primary/mapped adapters |
| **Authorization** | Bindings, scope lenses, structured outcomes |
| **Operator** | Seed presets, backup/GCS, record history, validation, markdown/diagrams |
| **CLI** | `catalox` — firestore, seed, items, toolbox, history, catalog |

---

## Install

```bash
npm install @x12i/catalox-engine @x12i/catalox-contracts
```

Requires **Node `>=20`**.

---

## Import surfaces

| Subpath | Export |
|---------|--------|
| `@x12i/catalox-engine` | Full index (embedder + operator re-exports) |
| `@x12i/catalox-engine/embedder` | `createCatalox`, `Catalox`, adapters, errors |
| `@x12i/catalox-engine/operator` | Backup, GCS, bindings, ContextResolver, etc. |
| `@x12i/catalox-engine/firebase` | `createCataloxFromEnv`, `testFirestoreConnectionFromEnv` |
| `@x12i/catalox-engine/mongo` | `createCataloxFromMongoEnv`, `MongoStore` |
| `@x12i/catalox-engine/mapping` | `validateMappingSpec`, `executeMapping` |

Equivalent paths on root package: `@x12i/catalox/embedder`, `/firebase`, etc.

---

## Quick start

```ts
import { createCataloxFromEnv } from "@x12i/catalox-engine/firebase";

const { catalox } = createCataloxFromEnv();
const scoped = catalox.withContext({ appId: "myApp" });
const { listOutcome, items } = await scoped.listCatalogItems("signals", { limit: 50 });
```

```bash
# CLI (after build)
node dist/cli/index.js firestore probe
# or: npx catalox (via @x12i/catalox / @x12i/catalox-cli)
```

---

## Build & test

```bash
npm run build -w @x12i/catalox-engine
npm test -w @x12i/catalox-engine
npm run test:integration -w @x12i/catalox-engine  # live Firestore
```

---

## Package layout

| Path | Purpose |
|------|---------|
| `src/catalox/` | Core `Catalox` class, bound context, seed presets |
| `src/firebase/` | Firestore stores, bootstrap |
| `src/mongo/` | Mongo persistence |
| `src/cli/` | Commander CLI entry |
| `src/mapping/` | Mapped catalog field mapping |
| `presets/` | Built-in seed manifest presets |
| `schemas/` | JSON schemas for manifests |
| `test/` | Unit + integration tests |

---

## Dependencies

- `@x12i/catalox-contracts` — shared types
- `firebase-admin`, `mongodb`, `@google-cloud/storage`
- `@x12i/helpers`, `@x12i/logxer`
- Optional: `react`, `react-dom` (renderer snippet HTML path)

---

## Documentation

- [Root README](../../README.md) — overview and doc index
- [Onboarding](../../docs/onboarding-happy-path.md)
- [Environment](../../docs/environment.md)
- [Native storage](../../docs/native-catalog-storage-and-api.md)
- [CLI items](../../docs/cli-items.md)
- [Deployment](../../docs/DEPLOYMENT.md)

---

## Related packages

| Package | Relationship |
|---------|--------------|
| `@x12i/catalox-contracts` | Types consumed by engine |
| `@x12i/catalox-api` | HTTP wrapper over this engine |
| `@x12i/catalox-cli` | Bin re-export of this package's CLI |