@x12i/catalox 5.1.3 → 5.9.6

package/docs/cli-items.md

@@ -1,94 +0,0 @@
-# `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 + smart properties). Offline: `--file` with `--catalog-type` or `--catalog` + `--app`. Use **`--no-auto-create`** to fail when smart-property target codes are missing (no auto-create during validate). 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

@@ -1,65 +0,0 @@
-# `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/docs/cli-toolbox.md

@@ -1,166 +0,0 @@
-# `catalox toolbox` — access diagnostics and binding repairs
-
-The **`toolbox`** CLI commands help operators answer: **“Can this `appId` read this `catalogId` in Firestore, and why not?”** They complement **`catalox report`** / **`export`**, which support **`--god`** to **bypass** binding checks for inventory — not for reproducing embedder/runtime auth.
-
-## Prerequisites
-
-Use the **same environment** as other Catalox CLI commands (see [`docs/environment.md`](environment.md)):
-
-- **Firestore:** `FIREBASE_PROJECT_ID`, optional `FIRESTORE_DATABASE_ID`, and credentials (`GOOGLE_SERVICE_ACCOUNT_BASE64` recommended, or ADC).
-- **Working directory:** `.env` loaded via `dotenv` from `src/cli/index.ts` (same pattern as `catalox firestore probe`).
-
-Connectivity smoke test:
-
-```bash
-catalox firestore probe
-```
-
-## Firestore layout (what is checked)
-
-| Piece | Collection / id | Meaning |
-|-------|------------------|--------|
-| Catalog row | `catalogs/{catalogId}` | Catalog exists in this project. |
-| App↔catalog binding | `catalogBindings/{appId}:{catalogId}` | Document id is **`{appId}:{catalogId}`** (see [`src/firebase/binding-store.ts`](../src/firebase/binding-store.ts), [`src/catalox/catalox.ts`](../src/catalox/catalox.ts) `bindCatalogToApp`). |
-
-Runtime reads require an **active** binding with sufficient **`access`** flags (`canRead` for list/get, etc.). See [`docs/authorization.md`](authorization.md) and [`docs/spec.md`](spec.md) §13 (app↔catalog binding model).
-
-## `toolbox check-access`
-
-**Purpose:** In one shot, report:
-
-1. Whether the **`catalogBindings/{appId}:{catalogId}`** document exists and its fields (as stored).
-2. Whether **`catalogs/{catalogId}`** exists (via Catalox `getCatalog`, no binding required for that read).
-3. **`listCatalogItemsWithOutcome`** for `{ appId }` + `catalogId` with `limit: 1` — the same authorization path as normal embedder usage (unless you use `superAdmin` / god mode elsewhere).
-
-### Usage
-
-```bash
-catalox toolbox check-access --app <appId> --catalog <catalogId>
-```
-
-Optional:
-
-```bash
-catalox toolbox check-access --app <appId> --catalog <catalogId> --show-all-bindings
-```
-
-**`--show-all-bindings`** runs a Firestore query on `catalogBindings` where `catalogId == <catalogId>` and prints every matching row (useful to see which apps are bound to a shared catalog).
-
-### Interpreting the JSON
-
-| Field | Typical meaning |
-|-------|------------------|
-| `bindingDocId` | Always **`{appId}:{catalogId}`**. |
-| `bindingDocExists` / `binding` | If `false` / `null`, there is **no** (or unreadable) binding doc at that id — lists will be **denied** for that app. |
-| `catalogExists` | If `false`, there is **no** `catalogs/{catalogId}` document in **this** project (wrong project/database, typo, or catalog never created). **Fix:** create the catalog (seed, `createCatalog`, or your platform’s provisioning) — **`toolbox` does not create catalog rows.** |
-| `catalogMetadataStatus` | When the catalog exists, optional `metadata.status` from the catalog record. |
-| `simulatedListOutcome` | Result of `listCatalogItemsWithOutcome`: **`ok`**, **`empty`**, **`denied`**, **`misconfigured`**, **`mapping_blocked`**. See [`docs/outcomes.md`](outcomes.md). |
-| `deniedMessage` | Present when `simulatedListOutcome === "denied"`. |
-| `recommendations` | Short suggested next steps (heuristic). |
-
-### Exit code
-
-- **0** when `simulatedListOutcome` is **`ok`** or **`empty`** (authorized; empty means no items returned with `limit: 1`).
-- **1** for **`denied`**, **`misconfigured`**, **`mapping_blocked`**, or unexpected errors — suitable for scripts.
-
-### Example: studio app and `entities`
-
-If your host uses `appId` **`graphs-studio`** and catalog id **`entities`**:
-
-```bash
-catalox toolbox check-access --app graphs-studio --catalog entities
-```
-
-If you see **`catalogExists: false`** and **`bindingDocExists: false`**, you must:
-
-1. **Create the catalog** in this Firestore project (so `catalogs/entities` exists), then
-2. **Create the binding** (next section).
-
-If the catalog exists but **`bindingDocExists` is false**, only step (2) is required.
-
-## `toolbox ensure-binding`
-
-**Purpose:** Call Catalox **`ensureBinding`** — **insert** `catalogBindings/{appId}:{catalogId}` **only when no binding row already exists** for that app+catalog pair.
-
-It does **not**:
-
-- Create **`catalogs/{catalogId}`**.
-- Upgrade or reactivate an existing row (if a doc exists, **`ensureBinding` is a no-op**).
-
-### Usage
-
-```bash
-catalox toolbox ensure-binding --app <appId> --catalog <catalogId>
-```
-
-Optional flags:
-
-- **`--write`** — set `canWrite: true` on the **new** binding (default `false`).
-- **`--admin`** — set `canAdmin: true`.
-- **`--god`** — set `superAdmin` on the Catalox context. Needed only when your **context `appId`** differs from the **`--app`** binding target (see **`ensureBinding`** in [`src/catalox/catalox.ts`](../src/catalox/catalox.ts)). The toolbox sets context **`appId`** from **`--app`**, so **`--god` is usually not required** for normal “bind this app to this catalog” use.
-
-### After `ensure-binding`
-
-Re-run:
-
-```bash
-catalox toolbox check-access --app <appId> --catalog <catalogId>
-```
-
-If the binding doc existed but was **disabled** or had **wrong `access`**, `ensure-binding` will not change it — use **`repair-binding`** below.
-
-## `toolbox repair-binding`
-
-**Purpose:** **Merge-write** the `catalogBindings/{appId}:{catalogId}` document to **`status: "active"`** and the given **`access`** flags. Use when:
-
-- A binding exists but **`status`** is not **`active`**, or
-- **`canRead`** / **`canWrite`** need to be corrected, or
-- **`ensure-binding`** no-ops because a row already exists.
-
-### Usage
-
-**`--god` is required** (operator confirmation; the write uses Firebase Admin and bypasses client security rules like other admin tooling).
-
-```bash
-catalox toolbox repair-binding --god --app <appId> --catalog <catalogId>
-```
-
-Optional:
-
-- **`--write`** — set `canWrite: true`.
-- **`--admin`** — set `canAdmin: true`.
-
-Then verify with **`check-access`** again.
-
-## `toolbox unbind-catalog`
-
-**Purpose:** Call Catalox **`unbindCatalogFromApp`**, which **disables** the binding at `catalogBindings/{appId:catalogId}` (`status: "disabled"`) rather than deleting the document. The app stops receiving read/write access until the row is repaired or re-bound.
-
-### Usage
-
-```bash
-catalox toolbox unbind-catalog --app <appId> --catalog <catalogId>
-```
-
-Use **`--god`** when your CLI context (typically `CATALOX_APP_ID`) is not the same as **`--app`** and the library requires super-admin for cross-app operations (same mental model as `ensure-binding`).
-
-### After `unbind-catalog`
-
-- Re-run **`toolbox check-access`** — expect `bindingDocExists: true` with `status: "disabled"` or list outcome **denied**, depending on how your host reads bindings.
-- To restore access without re-seeding: **`toolbox repair-binding --god`** (sets `active` and access flags).
-
-## How this differs from `report` / `export --god`
-
-| Tool | Binding checks |
-|------|------------------|
-| **`catalox report`**, **`export`** with **`--god`** | Super-admin context can **skip** binding requirements for broad inventory. |
-| **`toolbox check-access`** | Uses **normal** app context (no `--god` on check-access) so **`listCatalogItemsWithOutcome`** reflects **real** embedder access. |
-| **`ensure-binding`** / **`repair-binding`** | **Writes** binding documents (admin SDK); **`repair-binding`** requires **`--god`**. |
-
-## Related documentation
-
-- [`docs/authorization.md`](authorization.md) — app axis, super admin, empty vs denied.
-- [`docs/outcomes.md`](outcomes.md) — `listCatalogItemsWithOutcome` outcomes.
-- [`docs/onboarding-happy-path.md`](onboarding-happy-path.md) — seed presets that include catalogs and bindings.
-- [`docs/spec.md`](spec.md) §13 — app↔catalog binding model.
-- [`docs/cli-items.md`](cli-items.md) — per-item CRUD, batch upsert, `seed validate`, and relation subcommands.

package/firestore.indexes.json

@@ -1,39 +0,0 @@
-{
-  "indexes": [
-    {
-      "collectionGroup": "catalogItemHistory",
-      "queryScope": "COLLECTION",
-      "fields": [
-        { "fieldPath": "catalogId", "order": "ASCENDING" },
-        { "fieldPath": "ts", "order": "DESCENDING" }
-      ]
-    },
-    {
-      "collectionGroup": "catalogItemHistory",
-      "queryScope": "COLLECTION",
-      "fields": [
-        { "fieldPath": "catalogId", "order": "ASCENDING" },
-        { "fieldPath": "itemId", "order": "ASCENDING" },
-        { "fieldPath": "ts", "order": "DESCENDING" }
-      ]
-    },
-    {
-      "collectionGroup": "catalogItemHistory",
-      "queryScope": "COLLECTION",
-      "fields": [
-        { "fieldPath": "catalogId", "order": "ASCENDING" },
-        { "fieldPath": "op", "order": "ASCENDING" },
-        { "fieldPath": "ts", "order": "DESCENDING" }
-      ]
-    },
-    {
-      "collectionGroup": "catalogItemHistory",
-      "queryScope": "COLLECTION",
-      "fields": [
-        { "fieldPath": "catalogId", "order": "ASCENDING" },
-        { "fieldPath": "ts", "order": "ASCENDING" }
-      ]
-    }
-  ],
-  "fieldOverrides": []
-}