@x12i/catalox 4.1.0 → 4.2.0

package/docs/cli-items.md

@@ -1,93 +1,94 @@
-# `catalox items` — catalog item operators
-
-Operator-focused commands over the same [`Catalox`](../src/catalox/catalox.ts) APIs your app uses. Environment matches other CLIs (see [`docs/environment.md`](environment.md)): `FIREBASE_PROJECT_ID`, credentials, optional `CATALOX_STORE_ID`, **`CATALOX_APP_ID`** (or pass `--app` per command), optional `CATALOX_USER_ID` for actor attribution.
-
-Connectivity smoke test:
-
-```bash
-catalox firestore probe
-```
-
-## Auth and binding
-
-- Reads (`get`, `list`, `export`, `validate` with item) require a **read** binding for `--app` + catalog.
-- Writes (`upsert`, `patch`, `delete`, `batch-upsert`, `relation upsert/delete`) require **write** access where the underlying API enforces it.
-- **`--god`** sets `superAdmin` on the Catalox context (inventory-style bypass where the library allows it; **non-global native scopes still require super-admin** per `assertSuperAdminForNonGlobalScope`).
-- **`--store <storeId>`** overrides `CATALOX_STORE_ID` when your deployment is store-scoped.
-
-## JSON body shapes (`upsert`, `patch`, `relation`)
-
-Native upsert/patch accept the same logical shape as seed manifest rows:
-
-- **Preferred (matches `seed` `items[]`):** `{ "data": { /* identity + fields */ }, "scope": { ... }, "relations": [ ... ] }` — the CLI flattens this to what [`stripReservedWriteFields`](../src/catalox/catalox.ts) expects.
-- **Alternate:** put catalog field keys at the **top level** together with optional `scope`, `relations`, `indexed`, `references`.
-
-`items relation upsert` / `delete` expect JSON matching [`UpsertCatalogItemRelationInput` / `DeleteCatalogItemRelationInput`](../src/contracts/inputs.ts) (see also `items relation delete` for `referenceId` form).
-
-## Commands
-
-| Command | Purpose |
-|--------|---------|
-| `items validate` | `validateCatalog` (catalog-wide; currently a stub that reports valid) or `validateCatalogItem` when `--item` is set (relation rules vs descriptor). Exit **1** when item validation fails. |
-| `items get` | `getCatalogItem`. Exit **1** if `not_found` or `mapping_blocked`. |
-| `items list` | `listCatalogItemsWithOutcome`. Exit **1** unless outcome is `ok` or `empty`. Optional `--filter-json`, `--cursor` (mapped API catalogs). |
-| `items upsert` | `upsertNativeCatalogItem`. Body from `--file` or **stdin**. |
-| `items patch` | `updateNativeCatalogItem`. Requires `--item`. |
-| `items delete` | `deleteNativeCatalogItem`. Requires **`--confirm`**. |
-| `items batch-upsert` | `batchUpsertNativeCatalogItems`. Input is a **JSON array** or **NDJSON** (one object per line). Firestore batches internally in chunks of 450 writes. |
-| `items export` | Stable `{ catalogId, exportedCount, truncated, items }` JSON. Paginates with **`nextCursor`** when the mapped API adapter returns it; otherwise uses **`offset`** (native + mongo). Cap with `--max-total` (default 10000). |
-
-### Examples
-
-Validate relation rules for one item:
-
-```bash
-catalox items validate --app my-app --catalog entities --item some-id
-```
-
-Upsert from a file:
-
-```bash
-catalox items upsert --app my-app --catalog entities --file ./row.json
-```
-
-Batch from NDJSON:
-
-```bash
-catalox items batch-upsert --app my-app --catalog entities --file ./rows.ndjson
-```
-
-Export (pretty-printed):
-
-```bash
-catalox items export --app my-app --catalog entities --pretty --out entities-items.json
-```
-
-## `catalox seed validate`
-
-Parse and AJV-validate a manifest the same way `seed apply` loads it (`--file` or `--preset`). **No Firestore writes.** Prints counts and exits **0** on success.
-
-```bash
-catalox seed validate --preset builtin:native-map-v1
-```
-
-## When to use `seed apply` vs `items batch-upsert`
-
-- **`seed apply`** — one manifest: create catalogs if missing, optional descriptors/bindings, then items. Idempotent catalog **creation** path.
-- **`items batch-upsert`** — fast native-only bulk upsert for an **existing** catalog with descriptor already present; no binding/catalog provisioning.
-
-## `catalox export` vs `items export`
-
-- **`catalox export`** ([`src/cli/index.ts`](../src/cli/index.ts)) — Multi-catalog **inventory** JSON across resolved app(s), optional `--include-items` with `--limit-per-catalog`, optional `--no-item-data`. Best for broad snapshots and reports.
-- **`catalox items export`** — One **`--catalog`**, stable `{ catalogId, items }` shape, deeper pagination (`--max-total`, `--page-size`). Best for round-tripping or re-processing a single catalog’s rows.
-
-## Related
-
-- [`docs/cli-toolbox.md`](cli-toolbox.md) — `check-access`, `ensure-binding`, `repair-binding`, **`unbind-catalog`**.
-- [`docs/onboarding-happy-path.md`](onboarding-happy-path.md) — seed presets including bindings.
-
-## Smoke checklist (manual)
-
-1. `catalox seed validate --preset builtin:native-map-v1` → `ok: true`.
-2. `catalox items list --app <app> --catalog <id> --limit 5` → outcome `ok` or `empty`.
-3. `catalox items export --app <app> --catalog <id> --max-total 20 --pretty` → JSON with `items` array.
+# `catalox items` — catalog item operators
+
+Operator-focused commands over the same [`Catalox`](../src/catalox/catalox.ts) APIs your app uses. Environment matches other CLIs (see [`docs/environment.md`](environment.md)): `FIREBASE_PROJECT_ID`, credentials, optional `CATALOX_STORE_ID`, **`CATALOX_APP_ID`** (or pass `--app` per command), optional `CATALOX_USER_ID` for actor attribution.
+
+Connectivity smoke test:
+
+```bash
+catalox firestore probe
+```
+
+## Auth and binding
+
+- Reads (`get`, `list`, `export`, `validate` with item) require a **read** binding for `--app` + catalog.
+- Writes (`upsert`, `patch`, `delete`, `batch-upsert`, `relation upsert/delete`) require **write** access where the underlying API enforces it.
+- **`--god`** sets `superAdmin` on the Catalox context (inventory-style bypass where the library allows it; **non-global native scopes still require super-admin** per `assertSuperAdminForNonGlobalScope`).
+- **`--store <storeId>`** overrides `CATALOX_STORE_ID` when your deployment is store-scoped.
+
+## JSON body shapes (`upsert`, `patch`, `relation`)
+
+Native upsert/patch accept the same logical shape as seed manifest rows:
+
+- **Preferred (matches `seed` `items[]`):** `{ "data": { /* identity + fields */ }, "scope": { ... }, "relations": [ ... ] }` — the CLI flattens this to what [`stripReservedWriteFields`](../src/catalox/catalox.ts) expects.
+- **Alternate:** put catalog field keys at the **top level** together with optional `scope`, `relations`, `indexed`, `references`.
+
+`items relation upsert` / `delete` expect JSON matching [`UpsertCatalogItemRelationInput` / `DeleteCatalogItemRelationInput`](../src/contracts/inputs.ts) (see also `items relation delete` for `referenceId` form).
+
+## Commands
+
+| Command | Purpose |
+|--------|---------|
+| `items validate` | `validateCatalog` (catalog config, mapping, catalogType registry) or `validateCatalogItem` (`--item`: relations + payload schema). Offline: `--file` with `--catalog-type` or `--catalog` + `--app`. Exit **1** on errors. See [`cli-validate-payload.md`](./cli-validate-payload.md). |
+| `items get` | `getCatalogItem`. Exit **1** if `not_found` or `mapping_blocked`. |
+| `items list` | `listCatalogItemsWithOutcome`. Exit **1** unless outcome is `ok` or `empty`. Optional `--filter-json`, `--cursor` (mapped API catalogs). |
+| `items upsert` | `upsertNativeCatalogItem`. Body from `--file` or **stdin**. |
+| `items patch` | `updateNativeCatalogItem`. Requires `--item`. |
+| `items delete` | `deleteNativeCatalogItem`. Requires **`--confirm`**. |
+| `items batch-upsert` | `batchUpsertNativeCatalogItems`. Input is a **JSON array** or **NDJSON** (one object per line). Firestore batches internally in chunks of 450 writes. |
+| `items export` | Stable `{ catalogId, exportedCount, truncated, items }` JSON. Paginates with **`nextCursor`** when the mapped API adapter returns it; otherwise uses **`offset`** (native + mongo). Cap with `--max-total` (default 10000). |
+
+### Examples
+
+Validate relation rules for one item:
+
+```bash
+catalox items validate --app my-app --catalog entities --item some-id
+```
+
+Upsert from a file:
+
+```bash
+catalox items upsert --app my-app --catalog entities --file ./row.json
+```
+
+Batch from NDJSON:
+
+```bash
+catalox items batch-upsert --app my-app --catalog entities --file ./rows.ndjson
+```
+
+Export (pretty-printed):
+
+```bash
+catalox items export --app my-app --catalog entities --pretty --out entities-items.json
+```
+
+## `catalox seed validate`
+
+Parse and AJV-validate a manifest the same way `seed apply` loads it (`--file` or `--preset`). **No Firestore writes.** Also validates `items[]` payloads when a schema resolves for the target catalog. Prints counts and exits **0** on success.
+
+```bash
+catalox seed validate --preset builtin:native-map-v1
+```
+
+## When to use `seed apply` vs `items batch-upsert`
+
+- **`seed apply`** — one manifest: create catalogs if missing, optional descriptors/bindings, then items. Idempotent catalog **creation** path.
+- **`items batch-upsert`** — fast native-only bulk upsert for an **existing** catalog with descriptor already present; no binding/catalog provisioning.
+
+## Export commands
+
+- **`catalox snapshot export`** ([`docs/cli-snapshot-export.md`](cli-snapshot-export.md)) — **`catalox-export/v1`**: multi-catalog, full pagination, deterministic ordering. Default **native** catalogs; use for backup and drift.
+- **`catalox export`** ([`src/cli/index.ts`](../src/cli/index.ts)) — Legacy **inventory** JSON; optional `--include-items` with `--limit-per-catalog`. Reports and shallow snapshots.
+- **`catalox items export`** — One **`--catalog`**, `{ catalogId, items }` shape; `--max-total`, `--page-size`. Single-catalog round-trip.
+
+## Related
+
+- [`docs/cli-toolbox.md`](cli-toolbox.md) — `check-access`, `ensure-binding`, `repair-binding`, **`unbind-catalog`**.
+- [`docs/onboarding-happy-path.md`](onboarding-happy-path.md) — seed presets including bindings.
+
+## Smoke checklist (manual)
+
+1. `catalox seed validate --preset builtin:native-map-v1` → `ok: true`.
+2. `catalox items list --app <app> --catalog <id> --limit 5` → outcome `ok` or `empty`.
+3. `catalox items export --app <app> --catalog <id> --max-total 20 --pretty` → JSON with `items` array.

package/docs/cli-snapshot-export.md

@@ -0,0 +1,65 @@
+# `catalox snapshot export` — catalog backup and drift
+
+Operator command for a **versioned**, **deterministic** JSON snapshot of Catalox catalog state. Output format: **`catalox-export/v1`**. Intended for disaster recovery artifacts, environment drift diff, and release audits — not for execution-matrix row state or Memorix corpora (see product FR scope).
+
+## Auth (read-only)
+
+- Requires **read** access on each exported catalog (`catalogBindings` + `canRead`).
+- No write, admin, or seed permissions are required.
+- **`--god`** sets `superAdmin` on the Catalox context and, by default, **super-lists all native physical rows** (every scope layer). Use for platform backups when the operator account is super-admin.
+- **`--no-all-native-scopes`** keeps listing scoped to the default tenant/global merge even with `--god`.
+
+Environment: same as other CLIs ([`environment.md`](environment.md)) — `FIREBASE_PROJECT_ID`, credentials, `CATALOX_APP_ID` or `--app`, optional `CATALOX_STORE_ID` / `--store`.
+
+## Scope
+
+| Flag | Effect |
+|------|--------|
+| _(default)_ | All **native** catalogs visible to `--app` |
+| `--catalog <id>...` | Subset of catalog ids |
+| `--catalog-type <type>...` | Filter `catalogType` |
+| `--include-mapped` | Also export mapped catalogs (mongo/api adapters) |
+| `--include-disabled` / `--include-hidden` | Include non-active or hidden catalogs |
+| `--no-item-data` | Items without `data` (metadata-only) |
+| `--page-size <n>` | Pagination chunk size (default 200, max 500) |
+| `--max-items-per-catalog <n>` | Stop after N items per catalog (`truncated: true`) |
+
+## Output shape (`catalox-export/v1`)
+
+- `format`: `"catalox-export/v1"`
+- `exportedAt`: ISO timestamp
+- `consistency`: `"best-effort"` (no cross-catalog transaction; suitable for structural diff, not strict point-in-time isolation)
+- `context`: `appId`, optional `storeId`, `userId`, `superAdmin`
+- `catalogs[]`: sorted by `catalogId`; each block has `catalog` metadata, `items[]` sorted by `itemId`, `itemCount`, optional `truncated`, `listOutcome`, `issues`
+
+Stable field names and ordering are preserved across patch releases for this format version.
+
+## Examples
+
+All native catalogs to a file (typical pre-migration backup):
+
+```bash
+catalox snapshot export --app "$CATALOX_APP_ID" --god --pretty --out "./backup-$(date -u +%Y%m%d).json"
+```
+
+Staging vs production drift (same flags, then `diff`):
+
+```bash
+catalox snapshot export --app my-app --catalog graphs execution-matrix --out staging.json
+catalox snapshot export --app my-app --catalog graphs execution-matrix --out prod.json
+diff -u staging.json prod.json
+```
+
+## Related commands
+
+| Command | When to use |
+|---------|-------------|
+| **`catalox snapshot export`** | Product-owned **multi-catalog** backup/drift contract |
+| `catalox items export` | Single catalog, `{ catalogId, items }` shape |
+| `catalox export` | Legacy **inventory** report JSON (`--include-items` + per-catalog limits) |
+| `catalox firestore backup` | Raw Firestore NDJSON + GCS manifest (infra-level) |
+
+## Verification matrix
+
+1. **Unit:** `npm run test:unit` — `catalog-snapshot-export.test.ts`
+2. **Live Firestore** (`FIRESTORE_LIVE_TESTS=1`): integration test exercises `exportCatalogSnapshot` with multiple upserted items and pagination-sized `pageSize`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/catalox",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Platform infrastructure for reusable, interoperable catalogs across apps and data sources.",
   "license": "MIT",
   "private": false,
@@ -51,8 +51,10 @@
     "dist",
     "docs/catalox-ui-contract.md",
     "docs/cli-items.md",
+    "docs/cli-snapshot-export.md",
     "docs/cli-toolbox.md",
     "presets",
+    "schemas",
     "README.md",
     "LICENSE",
     "firestore.indexes.json"

package/presets/native-map-v1.json

@@ -7,9 +7,21 @@
     {
       "catalogId": "catalox_native_map",
       "name": "Native map",
-      "catalogType": "generic",
+      "catalogType": "generic-map",
+      "schemaVersion": "catalox.payload.generic-map/v1",
       "sourceMode": "native",
-      "native": {}
+      "native": {
+        "itemSchema": {
+          "$id": "catalox.payload.generic-map/v1",
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["key"],
+          "properties": {
+            "key": { "type": "string", "minLength": 1 },
+            "value": {}
+          }
+        }
+      }
     }
   ],
   "descriptors": [

package/schemas/native-map-item/v1.json

@@ -0,0 +1,10 @@
+{
+  "$id": "catalox.payload.generic-map/v1",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["key"],
+  "properties": {
+    "key": { "type": "string", "minLength": 1 },
+    "value": {}
+  }
+}

package/schemas/registry.json

@@ -0,0 +1,3 @@
+{
+  "catalox.payload.generic-map/v1": "native-map-item/v1.json"
+}