@x12i/catalox 4.2.0 → 5.0.0

package/dist/src/catalox/scope-legacy-convert.js

@@ -0,0 +1,177 @@
+const CX = "cx~";
+const V2 = "v2";
+function b64uDec(s) {
+    return Buffer.from(s, "base64url").toString("utf8");
+}
+/** Decode legacy `cx~` storage document ids (migration only). */
+export function decodeNativeItemStorageDocId(docId) {
+    if (!docId.startsWith(CX)) {
+        return { logicalItemId: docId, legacyScope: { kind: "global" } };
+    }
+    const rest = docId.slice(CX.length);
+    const parts = rest.split("~");
+    if (parts[0] === V2) {
+        const last = parts[parts.length - 1];
+        if (!last)
+            return null;
+        const logicalItemId = b64uDec(last);
+        const scoped = { kind: "scoped", tenant: {}, agent: {} };
+        for (let i = 1; i < parts.length - 1; i += 2) {
+            const k = parts[i];
+            const v = parts[i + 1];
+            if (!k || !v)
+                break;
+            const dec = b64uDec(v);
+            const t = scoped.tenant;
+            const a = scoped.agent;
+            if (k === "ac")
+                t.accountId = dec;
+            else if (k === "g")
+                t.groupId = dec;
+            else if (k === "u")
+                t.userId = dec;
+            else if (k === "ch")
+                t.channelId = dec;
+            else if (k === "v")
+                t.visitorId = dec;
+            else if (k === "d")
+                a.domainId = dec;
+            else if (k === "ag")
+                a.agentId = dec;
+        }
+        return { logicalItemId, legacyScope: scoped };
+    }
+    if (parts[0] === "a" && parts.length === 3) {
+        return { logicalItemId: b64uDec(parts[2]), legacyScope: { kind: "account", accountId: b64uDec(parts[1]) } };
+    }
+    if (parts[0] === "ag" && parts.length === 4) {
+        return {
+            logicalItemId: b64uDec(parts[3]),
+            legacyScope: { kind: "agent", accountId: b64uDec(parts[1]), agentId: b64uDec(parts[2]) },
+        };
+    }
+    if (parts[0] === "u" && parts.length === 4) {
+        return {
+            logicalItemId: b64uDec(parts[3]),
+            legacyScope: { kind: "user", accountId: b64uDec(parts[1]), userId: b64uDec(parts[2]) },
+        };
+    }
+    return null;
+}
+function arr1(v) {
+    if (v == null || String(v).trim() === "")
+        return undefined;
+    return [String(v).trim()];
+}
+function unionDim(target, dim, vals) {
+    const prev = target[dim] ?? [];
+    target[dim] = [...new Set([...prev, ...vals])];
+}
+function normalizeStringArray(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return [...new Set(raw.filter((x) => typeof x === "string" && x.trim() !== "").map((s) => s.trim()))];
+}
+/**
+ * Convert legacy stored scope + metadata tags to flexible scope (migration / allowLegacy reads).
+ */
+export function convertLegacyScopeToFlexible(scope, metadata) {
+    const out = {};
+    const meta = metadata ?? {};
+    const domainIds = normalizeStringArray(meta.domainIds);
+    const agentIds = normalizeStringArray(meta.agentIds);
+    if (domainIds.length)
+        unionDim(out, "domains", domainIds);
+    if (agentIds.length)
+        unionDim(out, "agents", agentIds);
+    if (scope == null || typeof scope !== "object") {
+        return out;
+    }
+    const o = scope;
+    const kind = o.kind;
+    if (kind === "global" || kind == null) {
+        return out;
+    }
+    if (kind === "scoped") {
+        const tenant = o.tenant;
+        const agent = o.agent;
+        if (tenant) {
+            const ac = arr1(tenant.accountId);
+            if (ac)
+                unionDim(out, "accounts", ac);
+            const g = arr1(tenant.groupId);
+            if (g)
+                unionDim(out, "groups", g);
+            const u = arr1(tenant.userId);
+            if (u)
+                unionDim(out, "users", u);
+            const ch = arr1(tenant.channelId);
+            if (ch)
+                unionDim(out, "channels", ch);
+            const v = arr1(tenant.visitorId);
+            if (v)
+                unionDim(out, "visitors", v);
+        }
+        if (agent) {
+            const d = arr1(agent.domainId);
+            if (d)
+                unionDim(out, "domains", d);
+            const ag = arr1(agent.agentId);
+            if (ag)
+                unionDim(out, "agents", ag);
+        }
+        return out;
+    }
+    if (kind === "account" && typeof o.accountId === "string") {
+        unionDim(out, "accounts", [o.accountId]);
+        unionDim(out, "agents", normalizeStringArray(o.agentIds));
+        unionDim(out, "users", normalizeStringArray(o.userIds));
+        return out;
+    }
+    if (kind === "agent" && typeof o.accountId === "string" && typeof o.agentId === "string") {
+        unionDim(out, "accounts", [o.accountId]);
+        unionDim(out, "agents", [o.agentId]);
+        return out;
+    }
+    if (kind === "user" && typeof o.accountId === "string" && typeof o.userId === "string") {
+        unionDim(out, "accounts", [o.accountId]);
+        unionDim(out, "users", [o.userId]);
+        return out;
+    }
+    return out;
+}
+export function applyAgentScopeMapping(scope, accountId, agentId, mapping) {
+    if (!mapping)
+        return scope;
+    const key = `${accountId}:${agentId}`;
+    const m = mapping[key];
+    if (!m?.domains?.length)
+        return scope;
+    const out = { ...scope };
+    unionDim(out, "domains", m.domains);
+    if (m.agents?.length)
+        unionDim(out, "agents", m.agents);
+    return out;
+}
+/** Stable fingerprint for migration payload equivalence checks. */
+export function payloadFingerprint(data) {
+    return JSON.stringify(data, Object.keys(data).sort());
+}
+export function unionFlexibleScopes(scopes) {
+    const out = {};
+    for (const s of scopes) {
+        for (const [dim, vals] of Object.entries(normalizeFlexibleOnly(s))) {
+            unionDim(out, dim, vals);
+        }
+    }
+    return out;
+}
+function normalizeFlexibleOnly(scope) {
+    const out = {};
+    for (const [k, v] of Object.entries(scope)) {
+        if (v?.length)
+            out[k] = [...new Set(v)];
+    }
+    return out;
+}
+//# sourceMappingURL=scope-legacy-convert.js.map

package/dist/src/catalox/scope-legacy-convert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-legacy-convert.js","sourceRoot":"","sources":["../../../src/catalox/scope-legacy-convert.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/index.js

@@ -24,16 +24,37 @@ function resolvedStoreId(cliStore) {
     const id = (cliStore ?? process.env.CATALOX_STORE_ID ?? "").trim();
     return id || undefined;
 }
+function parseScopeJson(raw) {
+    const t = raw?.trim();
+    if (!t)
+        return undefined;
+    const parsed = JSON.parse(t);
+    if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("scope JSON must be an object of string arrays");
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        if (!Array.isArray(v))
+            throw new Error(`scope.${k} must be a string array`);
+        out[k] = v.filter((x) => typeof x === "string" && x.trim() !== "");
+    }
+    return out;
+}
 function baseContext(opts) {
     const appId = (opts.app ?? process.env.CATALOX_APP_ID ?? "").trim();
     if (!appId)
         throw new Error("Missing --app or CATALOX_APP_ID");
     const userId = (process.env.CATALOX_USER_ID ?? "").trim() || undefined;
     const storeId = resolvedStoreId(opts.store);
+    const scope = parseScopeJson(opts.scopeJson) ??
+        parseScopeJson(process.env.CATALOX_SCOPE_JSON) ??
+        undefined;
     return {
         appId,
         ...(storeId ? { storeId } : {}),
         ...(opts.god ? { superAdmin: true } : {}),
+        ...(opts.unrestricted ? { unrestrictedScope: true } : {}),
+        ...(scope ? { scope } : {}),
         ...(userId ? { userId, actor: { type: "user", id: userId } } : {}),
     };
 }
@@ -441,16 +462,35 @@ itemsCmd
     .requiredOption("--catalog <catalogId>", "Catalog id")
     .requiredOption("--item <itemId>", "Logical item id")
     .option("--storage-doc-id <id>", "Native: target a specific physical storage doc id")
+    .option("--scope-json <json>", "Fetch scope narrowing (JSON object of string arrays)")
+    .option("--scoped-only", "Exclude generic items", false)
+    .option("--generic-only", "Return only generic items", false)
     .option("--out <path>", "Write JSON to file instead of stdout")
     .option("--god", "God mode", false)
+    .option("--scope-json-token <json>", "Token scope on context (defaults to CATALOX_SCOPE_JSON)")
     .action(async (opts) => {
     const catalox = createCatalox();
-    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    const fetchScope = parseScopeJson(opts.scopeJson != null ? String(opts.scopeJson) : undefined);
+    const ctx = baseContext({
+        app: opts.app,
+        store: opts.store,
+        god: opts.god,
+        ...(opts.scopeJsonToken != null ? { scopeJson: String(opts.scopeJsonToken) } : {}),
+    });
     const catalogId = String(opts.catalog);
     const itemId = String(opts.item);
     const storageDocId = opts.storageDocId != null && String(opts.storageDocId).trim() ? String(opts.storageDocId).trim() : undefined;
     const got = await catalox.getCatalogItem(ctx, catalogId, itemId, {
         ...(storageDocId ? { storageDocId } : {}),
+        ...(fetchScope || opts.scopedOnly || opts.genericOnly
+            ? {
+                scope: {
+                    ...(fetchScope ? { scope: fetchScope } : {}),
+                    ...(opts.scopedOnly ? { scopedOnly: true } : {}),
+                    ...(opts.genericOnly ? { genericOnly: true } : {}),
+                },
+            }
+            : {}),
     });
     await writeOrStdout(JSON.stringify(got, null, 2), opts.out);
     if (got.outcome !== "found")
@@ -466,11 +506,22 @@ itemsCmd
     .option("--offset <n>", "Offset (native)", (v) => Number(v), 0)
     .option("--cursor <token>", "Mapped catalogs: pass nextCursor from a prior response")
     .option("--filter-json <json>", "JSON object merged into list filter (compact empty strings ignored by server)")
+    .option("--scope-json <json>", "Fetch scope narrowing (JSON object of string arrays)")
+    .option("--scope-json-token <json>", "Token scope on context (defaults to CATALOX_SCOPE_JSON)")
+    .option("--scoped-only", "Exclude generic items", false)
+    .option("--generic-only", "Return only generic items", false)
+    .option("--no-generic", "Same as --scoped-only", false)
     .option("--out <path>", "Write JSON to file instead of stdout")
     .option("--god", "God mode", false)
     .action(async (opts) => {
     const catalox = createCatalox();
-    const ctx = baseContext({ app: opts.app, store: opts.store, god: opts.god });
+    const fetchScope = parseScopeJson(opts.scopeJson != null ? String(opts.scopeJson) : undefined);
+    const ctx = baseContext({
+        app: opts.app,
+        store: opts.store,
+        god: opts.god,
+        ...(opts.scopeJsonToken != null ? { scopeJson: String(opts.scopeJsonToken) } : {}),
+    });
     const catalogId = String(opts.catalog);
     let filter;
     const fj = opts.filterJson != null ? String(opts.filterJson).trim() : "";
@@ -481,9 +532,19 @@ itemsCmd
         }
         filter = parsed;
     }
+    const scopedOnly = Boolean(opts.scopedOnly || opts.noGeneric);
     const res = await catalox.listCatalogItemsWithOutcome(ctx, catalogId, {
         limit: opts.limit,
         offset: opts.offset,
+        ...(fetchScope || scopedOnly || opts.genericOnly
+            ? {
+                scope: {
+                    ...(fetchScope ? { scope: fetchScope } : {}),
+                    ...(scopedOnly ? { scopedOnly: true } : {}),
+                    ...(opts.genericOnly ? { genericOnly: true } : {}),
+                },
+            }
+            : {}),
         ...(filter ? { filter } : {}),
         ...(opts.cursor != null && String(opts.cursor).trim()
             ? { cursor: String(opts.cursor).trim() }
@@ -873,6 +934,37 @@ firestoreCmd
     if (!m.ok)
         process.exitCode = 1;
 });
+firestoreCmd
+    .command("migrate-native-item-scope")
+    .description("One-time: convert legacy/native scope shapes to flexible scope maps (domains[], agents[], …)")
+    .requiredOption("--app <appId>", "AppId for Catalox context")
+    .option("--dry-run", "Report only; no writes", false)
+    .option("--verify-only", "Fail if any legacy scope shapes remain", false)
+    .option("--i-have-backups", "Required to apply writes (not dry-run/verify-only)", false)
+    .option("--continue-on-error", "Continue other catalogs if one fails", false)
+    .option("--catalog <catalogId...>", "Limit to catalog ids")
+    .option("--scope-mapping <path>", "JSON map accountId:agentId → { domains, agents }")
+    .option("--also-export-files", "Write NDJSON under .catalox-migration-backups/", false)
+    .option("--god", "God mode", false)
+    .action(async (opts) => {
+    const catalox = createCatalox();
+    const ctx = baseContext({ app: opts.app, god: opts.god });
+    const exportDir = opts.alsoExportFiles
+        ? resolvePath(process.cwd(), ".catalox-migration-backups")
+        : undefined;
+    const m = await catalox.migrateNativeItemScope(ctx, {
+        dryRun: Boolean(opts.dryRun),
+        verifyOnly: Boolean(opts.verifyOnly),
+        iHaveBackups: Boolean(opts.iHaveBackups),
+        continueOnError: Boolean(opts.continueOnError),
+        ...(opts.catalog?.length ? { catalogIds: opts.catalog } : {}),
+        ...(opts.scopeMapping ? { scopeMappingPath: String(opts.scopeMapping) } : {}),
+        ...(exportDir ? { exportFilesDir: exportDir } : {}),
+    });
+    await writeOrStdout(JSON.stringify({ phase: "migrate-native-item-scope", result: m }, null, 2));
+    if (!m.ok)
+        process.exitCode = 1;
+});
 firestoreCmd
     .command("export-gcs")
     .description("Export Firestore collection(s) to a GCS bucket as NDJSON + manifest (for --all). Uses Application Default Credentials for GCS.")