@cross-deck/buckets 0.6.0 → 0.8.0

package/README.md

@@ -74,9 +74,24 @@ await bucket("pulse-map", async () => {
 });
 ```
 
-**3. That's it.** Open your Crossdeck dashboard and your operations are there —
-`pulse-map`, every other bucket you named, and an `unknown` row for anything you
-haven't named yet. Buckets counted them at the database driver, not in your code.
+**3. Read it back — right where you code.** Buckets writes a live readout to
+`.crossdeck/buckets.md` (biggest bucket first). Open it, or just ask your AI session
+**"read me my buckets"** — it's a plain file on disk, no dashboard required:
+
+```
+# Buckets — reads on this surface
+**32K reads** · 2026-06-19 (UTC)
+
+| bucket            | named | reads |
+| ----------------- | :---: | ----: |
+| headline-counters |   ✓   |   31K |
+| subscriptions     |   —   |  1.1K |
+```
+
+**No Crossdeck key needed for any of that.** `init()` with no `apiKey` meters locally
+and writes the readout — the free, no-account wedge. Add a key and it *also* reports
+up so the same numbers surface on your dashboard, with the drill-down, before/after,
+and read-spike alerts. (Set `mirror: false` to turn the local file off.)
 
 ---
 
@@ -296,6 +311,20 @@ about. Two grains:
 - **Tag a bucket** (coarse) — a whole handler or job: `bucket("pulse-map", handler)`
 - **Tag a single read** (fine) — one query: `bucket("owner-lookup", () => db.doc(id).get())`
 
+**Nest to drill down.** A `bucket()` inside another **composes into a path** —
+the dashboard reads that path as a tree, so you tag the biggest bucket, see what's
+under it, tag *that*, and the next-biggest surfaces. A tagged bucket also keeps the
+collection it read as the leaf, so you never lose where the units actually went:
+
+```ts
+await bucket("analytics", () =>
+  bucket("rollup", () => db.collection("events").where(/*…*/).get()));
+// → "analytics > rollup > col:events"
+```
+
+That waterfall — tag, drill, tag again — is how you walk a bill down from "where's
+it all going?" to the exact line, one ship at a time.
+
 `unknown` is never a dead end. It's a to-do with a one-line fix — exactly like a
 custom analytics event you haven't named yet. You tag until you've found your
 source; Buckets just shows the names resolving in.
@@ -318,6 +347,31 @@ primitive that the whole ecosystem can build on — so we open-sourced it, and w
 publish the rollup schema so you can consume it with any tool you like, including
 your own. **The best place to read Buckets data should be earned, never locked.**
 
+### Free with the collector — and what Crossdeck adds
+
+The collector is yours, free, forever: it meters every read on the surface you put
+it on, never costs you reads to *run*, and you can point it at your own sink and read
+the raw numbers yourself. That's a real tool on its own.
+
+Two honest limits come with going it alone — and they're exactly what Crossdeck is for:
+
+- **You see the surface you installed on.** Drop it in your server and you see server
+  reads — often the *minority*. Most apps read from the browser too (a separate
+  install), and the bill is the sum of both. **Crossdeck stitches server + browser +
+  every surface into one number**, so you stop reasoning from a slice.
+- **Reading the numbers back yourself costs a few reads** — querying your own stored
+  rollups is still a read. **Crossdeck maintains the summary and serves it to you free,
+  live, any time** — the cost tool never costs you to look.
+
+And because it's already wired in, Crossdeck turns the raw meter into the thing you
+*act* on: the **drill-down** (tag → see the next-biggest → tag again, down to the
+line), the **before/after fix verdict**, a **7-day baseline**, and **Slack alerts that
+page you before the invoice**. The numbers are identical on both sides — same counts,
+same source — Crossdeck just makes them whole, free to read, and impossible to miss.
+
+Getting there is one step you were taking anyway: **onboard, install the SDK once, and
+read-cost comes with it** — no second setup.
+
 ### Cost should page you like an exception — not surprise you like an invoice
 
 You already know what your code *should* do. You wrote the analytics pipeline; you

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { S as Sink } from './sink-DDQmzqm5.mjs';
-export { B as BucketsReport, O as OpCounts, R as ReportSink, a as ReportSinkConfig, b as ResourceCounts } from './sink-DDQmzqm5.mjs';
+import { S as Sink, B as BucketsReport } from './sink-B-i4E1fY.mjs';
+export { N as NullSink, O as OpCounts, R as ReportSink, a as ReportSinkConfig, b as ResourceCounts } from './sink-B-i4E1fY.mjs';
 
 /**
  * A resource unit — what an adapter counts. Firestore emits `read`/`write`/
@@ -102,15 +102,50 @@ declare function refineCostTag(patch: Partial<CostTag>): void;
 declare function currentCostTag(): CostTag;
 /**
  * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with
- * every operation inside it attributed to the bucket `name`; the attribution
- * rides the async subtree automatically. The one verb most developers ever touch:
+ * every operation inside it attributed to the bucket `name`; the attribution rides
+ * the async subtree automatically. NESTS: a `bucket()` inside another COMPOSES into
+ * a path (`"analytics" > "rollup"` → `"analytics>rollup"`), so the dashboard can
+ * drill from the coarse bucket down into its parts. The one verb most developers touch:
  *
- *   await bucket("nightly-export", async () => {
- *     const rows = await db.collection("events").where(...).get(); // → "nightly-export"
- *   });
+ *   await bucket("analytics", () =>
+ *     bucket("rollup", () => db.collection("events").where(...).get())); // → "analytics>rollup>col:events"
  */
 declare function bucket<T>(name: string, fn: () => T): T;
 
+declare const DEFAULT_MIRROR_DIR = ".crossdeck";
+/**
+ * Wraps an optional upstream sink. On each flush it writes the running day-total
+ * locally, THEN (if an upstream sink was given — i.e. a key) reports onward.
+ * With no upstream it is a pure local meter: the wedge, working with no account.
+ */
+declare class MirrorSink implements Sink {
+    private readonly upstream;
+    private readonly dir;
+    private acc;
+    private announced;
+    private seeded;
+    constructor(upstream: Sink | null, dir?: string);
+    private jsonPath;
+    /** Seed the running total once from an existing same-day file (survives restarts). */
+    private seed;
+    flush(report: BucketsReport): Promise<void>;
+}
+
+/**
+ * readout — renders the local file a developer (or their AI session) reads back with
+ * "read me my buckets". PURE string building: no I/O, no database reads. The node
+ * mirror (./mirror) writes this to `.crossdeck/buckets.md` on each flush, so the
+ * readout works offline, for free, with no account.
+ */
+
+/**
+ * The one line that closes every readout. Plain and factual: what the OSS shows you
+ * here, and what signing up adds — for free. No invented numbers, no urgency, no pitch.
+ */
+declare const READOUT_FOOTER: string;
+/** Render the day's coalesced report as a human/AI-readable markdown readout. */
+declare function renderReadout(report: BucketsReport): string;
+
 /**
  * @cross-deck/buckets — know exactly what every database read costs you, and who
  * caused it. A tiny, never-throws collector for Firestore.
@@ -122,8 +157,13 @@ declare function bucket<T>(name: string, fn: () => T): T;
  */
 
 interface InitOptions {
-    /** The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key. */
-    apiKey: string;
+    /**
+     * The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key.
+     * OPTIONAL: with no key, Buckets still meters locally and writes the readout to
+     * disk (`.crossdeck/buckets.md`) — the free, no-account wedge. Add a key and it
+     * also reports up to Crossdeck so the numbers surface on your dashboard.
+     */
+    apiKey?: string;
     /**
      * Pass the namespace from `firebase-admin/firestore` to auto-install the read
      * trap (recommended — this is what makes every read count with no per-call work).
@@ -137,14 +177,20 @@ interface InitOptions {
     flushIntervalMs?: number;
     /** Bring your own sink (self-host the rollups). Defaults to reporting up to Crossdeck. */
     sink?: Sink;
+    /**
+     * Where to write the local readout — the file "read me my buckets" reads back.
+     * Defaults to `.crossdeck`. Pass `false` to turn the local mirror off entirely.
+     */
+    mirror?: string | false;
     /** Notified when a flush fails, so a dropped window is never silent. Best-effort. */
     onError?: MeterConfig["onError"];
 }
 /**
- * Configure Buckets once, at process start. Points the meter at a sink (Crossdeck's
- * ingest by default) and — if you pass `firestore` — installs the universal read
- * trap so every read counts automatically.
+ * Configure Buckets once, at process start. Always meters locally and writes the
+ * readout to disk; if you pass `apiKey` (or your own `sink`) it ALSO reports up to
+ * Crossdeck. Pass `firestore` to install the universal read trap so every read counts
+ * automatically.
  */
-declare function init(options: InitOptions): void;
+declare function init(options?: InitOptions): void;
 
-export { type CostHint, type CostTag, type FirestoreClasses, type InitOptions, type MeterConfig, type OpType, type ResourceUnit, Sink, bucket, currentCostTag, enterCostTag, flush, init, init as initBuckets, installFirestoreMeter, record, recordDeletes, recordReads, recordWrites, refineCostTag, runWithCostTag };
+export { BucketsReport, type CostHint, type CostTag, DEFAULT_MIRROR_DIR, type FirestoreClasses, type InitOptions, type MeterConfig, MirrorSink, type OpType, READOUT_FOOTER, type ResourceUnit, Sink, bucket, currentCostTag, enterCostTag, flush, init, init as initBuckets, installFirestoreMeter, record, recordDeletes, recordReads, recordWrites, refineCostTag, renderReadout, runWithCostTag };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as Sink } from './sink-DDQmzqm5.js';
-export { B as BucketsReport, O as OpCounts, R as ReportSink, a as ReportSinkConfig, b as ResourceCounts } from './sink-DDQmzqm5.js';
+import { S as Sink, B as BucketsReport } from './sink-B-i4E1fY.js';
+export { N as NullSink, O as OpCounts, R as ReportSink, a as ReportSinkConfig, b as ResourceCounts } from './sink-B-i4E1fY.js';
 
 /**
  * A resource unit — what an adapter counts. Firestore emits `read`/`write`/
@@ -102,15 +102,50 @@ declare function refineCostTag(patch: Partial<CostTag>): void;
 declare function currentCostTag(): CostTag;
 /**
  * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with
- * every operation inside it attributed to the bucket `name`; the attribution
- * rides the async subtree automatically. The one verb most developers ever touch:
+ * every operation inside it attributed to the bucket `name`; the attribution rides
+ * the async subtree automatically. NESTS: a `bucket()` inside another COMPOSES into
+ * a path (`"analytics" > "rollup"` → `"analytics>rollup"`), so the dashboard can
+ * drill from the coarse bucket down into its parts. The one verb most developers touch:
  *
- *   await bucket("nightly-export", async () => {
- *     const rows = await db.collection("events").where(...).get(); // → "nightly-export"
- *   });
+ *   await bucket("analytics", () =>
+ *     bucket("rollup", () => db.collection("events").where(...).get())); // → "analytics>rollup>col:events"
  */
 declare function bucket<T>(name: string, fn: () => T): T;
 
+declare const DEFAULT_MIRROR_DIR = ".crossdeck";
+/**
+ * Wraps an optional upstream sink. On each flush it writes the running day-total
+ * locally, THEN (if an upstream sink was given — i.e. a key) reports onward.
+ * With no upstream it is a pure local meter: the wedge, working with no account.
+ */
+declare class MirrorSink implements Sink {
+    private readonly upstream;
+    private readonly dir;
+    private acc;
+    private announced;
+    private seeded;
+    constructor(upstream: Sink | null, dir?: string);
+    private jsonPath;
+    /** Seed the running total once from an existing same-day file (survives restarts). */
+    private seed;
+    flush(report: BucketsReport): Promise<void>;
+}
+
+/**
+ * readout — renders the local file a developer (or their AI session) reads back with
+ * "read me my buckets". PURE string building: no I/O, no database reads. The node
+ * mirror (./mirror) writes this to `.crossdeck/buckets.md` on each flush, so the
+ * readout works offline, for free, with no account.
+ */
+
+/**
+ * The one line that closes every readout. Plain and factual: what the OSS shows you
+ * here, and what signing up adds — for free. No invented numbers, no urgency, no pitch.
+ */
+declare const READOUT_FOOTER: string;
+/** Render the day's coalesced report as a human/AI-readable markdown readout. */
+declare function renderReadout(report: BucketsReport): string;
+
 /**
  * @cross-deck/buckets — know exactly what every database read costs you, and who
  * caused it. A tiny, never-throws collector for Firestore.
@@ -122,8 +157,13 @@ declare function bucket<T>(name: string, fn: () => T): T;
  */
 
 interface InitOptions {
-    /** The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key. */
-    apiKey: string;
+    /**
+     * The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key.
+     * OPTIONAL: with no key, Buckets still meters locally and writes the readout to
+     * disk (`.crossdeck/buckets.md`) — the free, no-account wedge. Add a key and it
+     * also reports up to Crossdeck so the numbers surface on your dashboard.
+     */
+    apiKey?: string;
     /**
      * Pass the namespace from `firebase-admin/firestore` to auto-install the read
      * trap (recommended — this is what makes every read count with no per-call work).
@@ -137,14 +177,20 @@ interface InitOptions {
     flushIntervalMs?: number;
     /** Bring your own sink (self-host the rollups). Defaults to reporting up to Crossdeck. */
     sink?: Sink;
+    /**
+     * Where to write the local readout — the file "read me my buckets" reads back.
+     * Defaults to `.crossdeck`. Pass `false` to turn the local mirror off entirely.
+     */
+    mirror?: string | false;
     /** Notified when a flush fails, so a dropped window is never silent. Best-effort. */
     onError?: MeterConfig["onError"];
 }
 /**
- * Configure Buckets once, at process start. Points the meter at a sink (Crossdeck's
- * ingest by default) and — if you pass `firestore` — installs the universal read
- * trap so every read counts automatically.
+ * Configure Buckets once, at process start. Always meters locally and writes the
+ * readout to disk; if you pass `apiKey` (or your own `sink`) it ALSO reports up to
+ * Crossdeck. Pass `firestore` to install the universal read trap so every read counts
+ * automatically.
  */
-declare function init(options: InitOptions): void;
+declare function init(options?: InitOptions): void;
 
-export { type CostHint, type CostTag, type FirestoreClasses, type InitOptions, type MeterConfig, type OpType, type ResourceUnit, Sink, bucket, currentCostTag, enterCostTag, flush, init, init as initBuckets, installFirestoreMeter, record, recordDeletes, recordReads, recordWrites, refineCostTag, runWithCostTag };
+export { BucketsReport, type CostHint, type CostTag, DEFAULT_MIRROR_DIR, type FirestoreClasses, type InitOptions, type MeterConfig, MirrorSink, type OpType, READOUT_FOOTER, type ResourceUnit, Sink, bucket, currentCostTag, enterCostTag, flush, init, init as initBuckets, installFirestoreMeter, record, recordDeletes, recordReads, recordWrites, refineCostTag, renderReadout, runWithCostTag };

package/dist/index.js

@@ -1,6 +1,8 @@
 'use strict';
 
 var async_hooks = require('async_hooks');
+var fs = require('fs');
+var path = require('path');
 
 // src/cost-context.ts
 var DEFAULT_TAG = {};
@@ -18,8 +20,11 @@ function refineCostTag(patch) {
 function currentCostTag() {
   return store.getStore() ?? DEFAULT_TAG;
 }
+var BUCKET_SEP = ">";
 function bucket(name, fn) {
-  return runWithCostTag({ ...currentCostTag(), label: name }, fn);
+  const parent = currentCostTag().label;
+  const path = parent ? `${parent}${BUCKET_SEP}${name}` : name;
+  return runWithCostTag({ ...currentCostTag(), label: path }, fn);
 }
 
 // src/cost-meter.ts
@@ -58,7 +63,8 @@ function record(resource, quantity, hint) {
     if (!Number.isFinite(quantity) || quantity <= 0) return;
     const t = currentCostTag();
     const date = utcDate();
-    const label = t.label || (hint?.collection ? `col:${hint.collection}` : "uncategorized");
+    const coll = hint?.collection ? `col:${hint.collection}` : null;
+    const label = t.label ? coll ? `${t.label}>${coll}` : t.label : coll ?? "uncategorized";
     const lk = date + SEP + resource + SEP + label;
     labelBuffer.set(lk, (labelBuffer.get(lk) ?? 0) + quantity);
     const hk = date + SEP + resource + SEP + utcHour();
@@ -157,6 +163,107 @@ var ReportSink = class {
     }
   }
 };
+var NullSink = class {
+  async flush() {
+  }
+};
+
+// src/readout.ts
+var READOUT_FOOTER = "Buckets OSS shows the reads on this surface. Sign up to Crossdeck (free) to see every surface in one view, drill any bucket down to the exact query, track a fix before and after, and get paged when reads spike \u2014 cross-deck.com";
+function fmt(n) {
+  if (n >= 1e6) return (n / 1e6).toFixed(2) + "M";
+  if (n >= 1e4) return Math.round(n / 1e3) + "K";
+  if (n >= 1e3) return (n / 1e3).toFixed(1) + "K";
+  return String(Math.round(n));
+}
+function isUntagged(label) {
+  const root = label.split(">")[0];
+  return root.startsWith("col:") || root === "uncategorized" || root === "unknown";
+}
+function displayLabel(label) {
+  return label.split(">").map((s) => s.startsWith("col:") ? s.slice(4) : s).join(" \u203A ");
+}
+function renderReadout(report) {
+  const entries = Object.entries(report.byLabel ?? {}).map(([label, counts]) => ({ label, reads: counts.read ?? 0 })).filter((e) => e.reads > 0).sort((a, b) => b.reads - a.reads);
+  const total = entries.reduce((s, e) => s + e.reads, 0);
+  const out = [];
+  out.push(`# Buckets \u2014 reads on this surface`);
+  out.push(``);
+  out.push(`**${fmt(total)} reads** \xB7 ${report.date} (UTC)`);
+  out.push(``);
+  if (entries.length === 0) {
+    out.push(`No reads metered yet \u2014 install the collector and let your app serve some traffic.`);
+  } else {
+    out.push(`| bucket | named | reads |`);
+    out.push(`| --- | :---: | ---: |`);
+    for (const e of entries) {
+      out.push(`| ${displayLabel(e.label)} | ${isUntagged(e.label) ? "\u2014" : "\u2713"} | ${fmt(e.reads)} |`);
+    }
+  }
+  out.push(``);
+  out.push(`---`);
+  out.push(READOUT_FOOTER);
+  out.push(``);
+  return out.join("\n");
+}
+
+// src/mirror.ts
+var DEFAULT_MIRROR_DIR = ".crossdeck";
+function mergeInto(target, src) {
+  if (!src) return;
+  for (const [key, counts] of Object.entries(src)) {
+    const bag = target[key] ??= {};
+    for (const [res, n] of Object.entries(counts)) {
+      if (typeof n === "number") bag[res] = (bag[res] ?? 0) + n;
+    }
+  }
+}
+var MirrorSink = class {
+  constructor(upstream, dir = DEFAULT_MIRROR_DIR) {
+    this.upstream = upstream;
+    this.dir = dir;
+  }
+  upstream;
+  dir;
+  acc = null;
+  announced = false;
+  seeded = false;
+  jsonPath() {
+    return path.join(this.dir, "buckets.json");
+  }
+  /** Seed the running total once from an existing same-day file (survives restarts). */
+  seed(date) {
+    if (this.seeded) return;
+    this.seeded = true;
+    try {
+      const prior = JSON.parse(fs.readFileSync(this.jsonPath(), "utf8"));
+      if (prior?.date === date && prior.byLabel) this.acc = prior;
+    } catch {
+    }
+  }
+  async flush(report) {
+    try {
+      this.seed(report.date);
+      if (!this.acc || this.acc.date !== report.date) {
+        this.acc = { date: report.date, byLabel: {}, byHour: {}, byMinute: {} };
+      }
+      mergeInto(this.acc.byLabel, report.byLabel);
+      mergeInto(this.acc.byHour ??= {}, report.byHour);
+      mergeInto(this.acc.byMinute ??= {}, report.byMinute);
+      fs.mkdirSync(this.dir, { recursive: true });
+      fs.writeFileSync(path.join(this.dir, "buckets.md"), renderReadout(this.acc));
+      fs.writeFileSync(this.jsonPath(), JSON.stringify(this.acc, null, 2));
+      if (!this.announced) {
+        this.announced = true;
+        console.log(
+          `Buckets: readout at ${path.join(this.dir, "buckets.md")} \u2014 open it, or ask your AI session to "read me my buckets".`
+        );
+      }
+    } catch {
+    }
+    if (this.upstream) await this.upstream.flush(report);
+  }
+};
 
 // src/adapters/firestore.ts
 var installed = false;
@@ -278,12 +385,17 @@ function installFirestoreMeter(classes) {
 }
 
 // src/index.ts
-function init(options) {
-  const sink2 = options.sink ?? new ReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });
+function init(options = {}) {
+  const upstream = options.sink ?? (options.apiKey ? new ReportSink({ apiKey: options.apiKey, endpoint: options.endpoint }) : null);
+  const sink2 = options.mirror === false ? upstream ?? new NullSink() : new MirrorSink(upstream, typeof options.mirror === "string" ? options.mirror : DEFAULT_MIRROR_DIR);
   configureMeter({ sink: sink2, flushIntervalMs: options.flushIntervalMs, onError: options.onError });
   if (options.firestore) installFirestoreMeter(options.firestore);
 }
 
+exports.DEFAULT_MIRROR_DIR = DEFAULT_MIRROR_DIR;
+exports.MirrorSink = MirrorSink;
+exports.NullSink = NullSink;
+exports.READOUT_FOOTER = READOUT_FOOTER;
 exports.ReportSink = ReportSink;
 exports.bucket = bucket;
 exports.currentCostTag = currentCostTag;
@@ -297,6 +409,7 @@ exports.recordDeletes = recordDeletes;
 exports.recordReads = recordReads;
 exports.recordWrites = recordWrites;
 exports.refineCostTag = refineCostTag;
+exports.renderReadout = renderReadout;
 exports.runWithCostTag = runWithCostTag;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map