@x12i/catalox 4.0.3 → 4.1.0

package/docs/cli-toolbox.md

@@ -0,0 +1,166 @@
+# `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/catalox",
-  "version": "4.0.3",
+  "version": "4.1.0",
   "description": "Platform infrastructure for reusable, interoperable catalogs across apps and data sources.",
   "license": "MIT",
   "private": false,
@@ -50,6 +50,8 @@
   "files": [
     "dist",
     "docs/catalox-ui-contract.md",
+    "docs/cli-items.md",
+    "docs/cli-toolbox.md",
     "presets",
     "README.md",
     "LICENSE",