@nysgpt/bucket-list 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brendan Stanton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# Bucket List
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lightweight search for S3.
+
+One command sweeps every bucket in your AWS account and writes a single
+self-contained HTML file: drill down from account to bucket to folder, with
+object counts, storage-class cost estimates, activity windows, largest files,
+common file-name patterns, and instant search across everything. The file works
+offline, in light and dark mode, and weighs a few hundred kilobytes even for
+accounts with millions of objects.
+
+```
+npx @nysgpt/bucket-list --open
+```
+
+## Why
+
+AWS's own answers to "what's in my S3?" are Storage Lens, which stops at
+bucket-level numbers, and S3 Inventory, which takes 24 hours and hands you
+Parquet files. Neither gives you an instant, browsable, shareable picture.
+Bucket List does, in minutes, for about a nickel per 10 million objects.
+
+## Requirements
+
+- The AWS CLI (v2) installed and configured with credentials that can list
+  buckets, list objects, and read CloudWatch metrics
+- Node.js 18+
+
+That's the whole stack. No SDK, no AI, no cloud service, no telemetry. If
+`aws s3 ls` works in your terminal, Bucket List works, whatever terminal,
+agent, or editor you run it from.
+
+## Usage
+
+```
+bucket-list [options]
+
+  --output <file>       output path            (default: bucket-list.html)
+  --buckets <a,b,c>     only these buckets     (default: every bucket)
+  --notes <file>        annotations JSON       (default: ./bucket-list.notes.json if present)
+  --concurrency <n>     parallel AWS calls     (default: 12)
+  --yes                 skip the cost estimate confirmation
+  --open                open the file when done
+```
+
+Before sweeping, it estimates the job from CloudWatch metrics and asks:
+
+```
+32 buckets, ~8,500,000 objects, ~2.1 TB (CloudWatch estimate).
+Sweep will make ~10,300 LIST requests: ~$0.05, roughly 6 min.
+Proceed? [y/N]
+```
+
+## What it does, exactly
+
+- Discovers every bucket with `list-buckets` and resolves each bucket's region.
+- Walks each bucket by folder, recursively splitting anything too large into
+  parallel streams, so a bucket with one five-million-object folder sweeps in
+  minutes instead of an hour.
+- Reads names, sizes, and dates only. It never downloads an object's contents
+  and never modifies anything. Glacier-stored objects are listed for free like
+  everything else.
+- Prices each bucket from CloudWatch per-storage-class metrics against the
+  us-east-1 list-price table, clearly labeled as an estimate.
+- Flags buckets where CloudWatch counts far more objects than the listing
+  shows, which usually means old versions kept by bucket versioning and
+  reclaimable with a lifecycle rule.
+
+## Annotations
+
+The generator knows nothing about your projects. If you want it to, drop a
+`bucket-list.notes.json` next to where you run it:
+
+```json
+{
+  "my-app-assets": { "verdict": "keep", "note": "serves production", "project": "my-app" },
+  "old-experiments": { "verdict": "disposable", "note": "rebuildable from source data" }
+}
+```
+
+Verdicts render as chips (`keep`, `review`, `disposable`, `empty`), notes
+appear on the bucket's row and page, and the columns only appear if you use
+them.
+
+## License
+
+MIT

package/bin/bucket-list.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+"use strict";
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const { spawnSync, spawn } = require("child_process");
+const { run, setConcurrency } = require("../lib/aws");
+const { discoverBuckets, estimate, sweepBucket } = require("../lib/sweep");
+const { render } = require("../lib/render");
+
+const VERSION = require("../package.json").version;
+
+const HELP = `Bucket List ${VERSION} — lightweight search for S3
+
+Sweeps every bucket in the AWS account your CLI is signed into and writes one
+self-contained HTML file: drill down by bucket and folder, object counts,
+storage-class cost estimates, largest files, and instant search. Works offline
+once generated. Requires the AWS CLI (v2) configured with list permissions.
+
+Usage: bucket-list [options]
+
+  --output <file>       output path            (default: bucket-list.html)
+  --buckets <a,b,c>     only these buckets     (default: every bucket)
+  --notes <file>        annotations JSON       (default: ./bucket-list.notes.json if present)
+  --concurrency <n>     parallel AWS calls     (default: 12)
+  --yes                 skip the cost estimate confirmation
+  --open                open the file when done
+  --version             print version
+  --help                this text
+
+Annotations file format (all fields optional):
+  { "my-bucket": { "verdict": "keep|review|disposable|empty",
+                   "note": "shown on the bucket's row and page",
+                   "project": "label under the bucket name" } }
+
+Cost note: the sweep itself uses S3 LIST requests at $0.005 per 1,000 — about
+five cents per 10 million objects — plus one CloudWatch query per 50 buckets.
+It reads names and sizes only; no object is ever downloaded or modified.`;
+
+function parseArgs(argv) {
+  const a = { output: "bucket-list.html", buckets: null, notes: null, concurrency: 12, yes: false, open: false };
+  for (let i = 0; i < argv.length; i++) {
+    const v = argv[i];
+    if (v === "--help" || v === "-h") { console.log(HELP); process.exit(0); }
+    else if (v === "--version") { console.log(VERSION); process.exit(0); }
+    else if (v === "--yes" || v === "-y") a.yes = true;
+    else if (v === "--open") a.open = true;
+    else if (v === "--output") a.output = argv[++i];
+    else if (v === "--buckets") a.buckets = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
+    else if (v === "--notes") a.notes = argv[++i];
+    else if (v === "--concurrency") a.concurrency = parseInt(argv[++i], 10) || 12;
+    else { console.error(`unknown option: ${v} (try --help)`); process.exit(2); }
+  }
+  return a;
+}
+
+function confirm(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (ans) => { rl.close(); resolve(/^y(es)?$/i.test(ans.trim())); });
+  });
+}
+
+function fmtBytes(b) {
+  if (b < 1024 ** 3) return (b / 1024 ** 2).toFixed(0) + " MB";
+  if (b < 1024 ** 4) return (b / 1024 ** 3).toFixed(1) + " GB";
+  return (b / 1024 ** 4).toFixed(2) + " TB";
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  setConcurrency(args.concurrency);
+
+  // 0. preconditions
+  const cliCheck = spawnSync("aws", ["--version"], { encoding: "utf8" });
+  if (cliCheck.error) {
+    console.error("The AWS CLI was not found. Install it and run `aws configure`, then retry.");
+    process.exit(1);
+  }
+  let account = "";
+  try {
+    const ident = await run(["sts", "get-caller-identity"]);
+    account = ident.Account || "";
+  } catch (e) {
+    console.error("AWS credentials aren't working: " + e.message);
+    console.error("Run `aws configure` (or set your profile/SSO session) and retry.");
+    process.exit(1);
+  }
+
+  // 1. discovery
+  process.stderr.write(`Discovering buckets in account ${account}...\n`);
+  const { buckets, skipped } = await discoverBuckets(args.buckets);
+  for (const s of skipped) process.stderr.write(`  skipping ${s.name}: no access to its region/location\n`);
+  if (!buckets.length) {
+    console.error("No buckets to sweep.");
+    process.exit(1);
+  }
+
+  // 2. estimate + guardrail
+  const stats = await estimate(buckets);
+  let estObjects = 0;
+  let estBytes = 0;
+  for (const b of buckets) {
+    const s = stats.get(b.name);
+    estObjects += s.cwObjects || 0;
+    estBytes += Object.values(s.classes).reduce((a, gb) => a + gb, 0) * 1024 ** 3;
+  }
+  const estRequests = Math.ceil((estObjects / 1000) * 1.2) + buckets.length * 3;
+  const estCost = (estRequests / 1000) * 0.005;
+  const estMinutes = Math.max(1, Math.round((estRequests * 0.12) / args.concurrency / 60));
+  process.stderr.write(
+    `${buckets.length} buckets, ~${estObjects.toLocaleString("en-US")} objects, ~${fmtBytes(estBytes)} (CloudWatch estimate).\n` +
+    `Sweep will make ~${estRequests.toLocaleString("en-US")} LIST requests: ~$${estCost < 0.005 ? "0.01" : estCost.toFixed(2)}, roughly ${estMinutes} min.\n`
+  );
+  if (!args.yes) {
+    if (!process.stdin.isTTY) {
+      console.error("Not a terminal; re-run with --yes to proceed without confirmation.");
+      process.exit(1);
+    }
+    const ok = await confirm("Proceed? [y/N] ");
+    if (!ok) {
+      console.error("Aborted. Nothing was swept.");
+      process.exit(0);
+    }
+  }
+
+  // 3. sweep
+  const t0 = Date.now();
+  const results = [];
+  let done = 0;
+  await Promise.all(
+    buckets.map(async (b) => {
+      try {
+        const r = await sweepBucket(b.name, b.region);
+        r.region = b.region;
+        results.push(r);
+      } catch (e) {
+        process.stderr.write(`  ${b.name}: FAILED (${e.message})\n`);
+        results.push({ bucket: b.name, region: b.region, n: 0, b: 0, largest: [], prefixes: [] });
+      }
+      done++;
+      process.stderr.write(`  [${done}/${buckets.length}] ${b.name}\n`);
+    })
+  );
+
+  // 4. annotations
+  let notes = {};
+  const notesPath = args.notes || (fs.existsSync("bucket-list.notes.json") ? "bucket-list.notes.json" : null);
+  if (notesPath) {
+    try {
+      notes = JSON.parse(fs.readFileSync(notesPath, "utf8"));
+      process.stderr.write(`Annotations loaded from ${notesPath}.\n`);
+    } catch (e) {
+      process.stderr.write(`Could not read ${notesPath}: ${e.message} (continuing without annotations)\n`);
+    }
+  }
+
+  // 5. render
+  const html = render({ results, stats, notes, account });
+  const out = path.resolve(args.output);
+  fs.writeFileSync(out, html);
+  const totalN = results.reduce((a, r) => a + r.n, 0);
+  const totalB = results.reduce((a, r) => a + r.b, 0);
+  const secs = Math.round((Date.now() - t0) / 1000);
+  process.stderr.write(
+    `\nSwept ${totalN.toLocaleString("en-US")} objects (${fmtBytes(totalB)}) across ${results.length} buckets in ${secs}s.\n`
+  );
+  console.log(out);
+
+  if (args.open) {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    spawn(opener, [out], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+  }
+}
+
+main().catch((e) => {
+  console.error(e.message || e);
+  process.exit(1);
+});

package/lib/aws.js

@@ -0,0 +1,107 @@
+"use strict";
+// Thin wrappers around the AWS CLI. No SDK, no dependencies: if `aws` works in
+// the user's terminal, Bucket List works, regardless of what else they use.
+const { spawn } = require("child_process");
+
+let MAX = 12;
+let active = 0;
+const queue = [];
+
+function setConcurrency(n) {
+  MAX = Math.max(1, n | 0);
+}
+
+function acquire() {
+  return new Promise((res) => {
+    if (active < MAX) {
+      active++;
+      res();
+    } else {
+      queue.push(res);
+    }
+  });
+}
+
+function release() {
+  active--;
+  if (queue.length) {
+    active++;
+    queue.shift()();
+  }
+}
+
+/** Run an aws CLI command, return parsed JSON (or raw text with json:false). */
+async function run(args, { json = true, region = null } = {}) {
+  await acquire();
+  try {
+    return await new Promise((resolve, reject) => {
+      const full = [...args];
+      if (json) full.push("--output", "json");
+      if (region) full.push("--region", region);
+      const p = spawn("aws", full, { stdio: ["ignore", "pipe", "pipe"] });
+      let out = "";
+      let err = "";
+      p.stdout.setEncoding("utf8");
+      p.stderr.setEncoding("utf8");
+      p.stdout.on("data", (d) => (out += d));
+      p.stderr.on("data", (d) => (err += d));
+      p.on("error", reject);
+      p.on("close", (code) => {
+        if (code !== 0) {
+          return reject(new Error(`aws ${args.slice(0, 3).join(" ")} failed: ${err.trim().slice(0, 300) || "exit " + code}`));
+        }
+        if (!json) return resolve(out);
+        try {
+          resolve(out.trim() ? JSON.parse(out) : {});
+        } catch (e) {
+          reject(new Error(`bad JSON from aws ${args[0]} ${args[1]}: ${e.message}`));
+        }
+      });
+    });
+  } finally {
+    release();
+  }
+}
+
+/**
+ * Stream `aws s3 ls <url> --recursive` line by line.
+ * Calls onObject(dateYYYYMMDD, sizeBytes, key) per object. Constant memory,
+ * works for millions of objects.
+ */
+async function streamLs(s3url, region, onObject) {
+  await acquire();
+  try {
+    return await new Promise((resolve, reject) => {
+      const args = ["s3", "ls", s3url, "--recursive"];
+      if (region) args.push("--region", region);
+      const p = spawn("aws", args, { stdio: ["ignore", "pipe", "pipe"] });
+      let buf = "";
+      let err = "";
+      const RE = /^(\d{4}-\d{2}-\d{2}) +\S+ +(\d+) (.*)$/;
+      p.stdout.setEncoding("utf8");
+      p.stderr.setEncoding("utf8");
+      p.stdout.on("data", (chunk) => {
+        buf += chunk;
+        let i;
+        while ((i = buf.indexOf("\n")) >= 0) {
+          const m = RE.exec(buf.slice(0, i));
+          buf = buf.slice(i + 1);
+          if (m) onObject(m[1], parseInt(m[2], 10), m[3]);
+        }
+      });
+      p.stderr.on("data", (d) => (err += d));
+      p.on("error", reject);
+      p.on("close", (code) => {
+        // `aws s3 ls` exits 1 on an empty prefix with no stderr — that's fine.
+        if (code !== 0 && err.trim()) {
+          return reject(new Error(`aws s3 ls ${s3url} failed: ${err.trim().slice(0, 300)}`));
+        }
+        resolve();
+      });
+    });
+  } finally {
+    release();
+  }
+}
+
+module.exports = { run, streamLs, setConcurrency };

package/lib/render.js

@@ -0,0 +1,457 @@
+"use strict";
+// Renders the sweep into a single self-contained HTML file:
+// hash-routed pages (catalog -> bucket -> folder), search, chart, dark mode.
+
+const MONTHS = ["", "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const CHIP = { keep: ["keep", "Keep"], review: ["review", "Review"], disposable: ["disp", "Disposable"], empty: ["disp", "Empty"] };
+
+function esc(s) {
+  return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function fmtB(b) {
+  if (b <= 0) return "0";
+  if (b < 1024) return b + " B";
+  if (b < 1024 ** 2) return Math.round(b / 1024) + " KB";
+  if (b < 1024 ** 3) return (b / 1024 ** 2).toFixed(1) + " MB";
+  return b < 100 * 1024 ** 3 ? (b / 1024 ** 3).toFixed(1) + " GB" : Math.round(b / 1024 ** 3) + " GB";
+}
+function fmtN(n) {
+  return n.toLocaleString("en-US");
+}
+function fmtD(d, thisYear) {
+  if (!d || d === "9999") return "";
+  const y = d.slice(0, 4), m = parseInt(d.slice(5, 7), 10), dd = parseInt(d.slice(8, 10), 10);
+  const base = MONTHS[m] + " " + dd;
+  return y === thisYear ? base : base + ", " + y;
+}
+function fmtWin(o, w, thisYear) {
+  const fo = fmtD(o, thisYear), fw = fmtD(w, thisYear);
+  if (!fo && !fw) return "–";
+  return fo === fw ? fo : fo + " – " + fw;
+}
+function fmtUsd(u) {
+  if (u >= 0.01) return u.toFixed(2);
+  return u > 0 ? "&lt;0.01" : "0";
+}
+function mostly(node) {
+  const bits = (node.x || []).slice(0, 2).filter(([, bb]) => bb > 0).map(([e, bb]) => esc(e) + " " + fmtB(bb));
+  return bits.length ? bits.join(" · ") : "–";
+}
+function chip(v) {
+  const c = CHIP[v];
+  return c ? '<span class="chip ' + c[0] + '"><span class="dot"></span>' + c[1] + "</span>" : "";
+}
+
+const CSS_VARS = [
+  "  :root { color-scheme: light; --page:#f9f9f7; --surface-1:#fcfcfb; --text-1:#0b0b0b; --text-2:#52514e; --muted:#898781; --grid:#e1e0d9; --baseline:#c3c2b7; --border:rgba(11,11,11,0.10); --series-1:#2a78d6; --good:#0ca30c; --warn:#fab219; --chip-keep-bg:rgba(12,163,12,0.10); --chip-review-bg:rgba(250,178,25,0.16); --chip-disp-bg:rgba(137,135,129,0.14); }",
+  "  @media (prefers-color-scheme: dark) { :root { color-scheme: dark; --page:#0d0d0d; --surface-1:#1a1a19; --text-1:#f0efec; --text-2:#c3c2b7; --muted:#898781; --grid:#2c2c2a; --baseline:#383835; --border:rgba(255,255,255,0.10); --series-1:#3987e5; --good:#0ca30c; --warn:#fab219; --chip-keep-bg:rgba(12,163,12,0.16); --chip-review-bg:rgba(250,178,25,0.14); --chip-disp-bg:rgba(137,135,129,0.18); } }",
+].join("\n");
+
+const CSS = [
+  "  * { box-sizing: border-box; }",
+  '  body { margin: 0; background: var(--page); color: var(--text-1); font: 15px/1.45 system-ui, -apple-system, "Segoe UI", sans-serif; padding: 28px 20px 48px; }',
+  "  .wrap { max-width: 1060px; margin: 0 auto; }",
+  "  h1 { font-size: 21px; font-weight: 650; margin: 0 0 2px; }",
+  "  .meta { color: var(--muted); font-size: 13px; margin-bottom: 26px; }",
+  "  .toprow { display: flex; gap: 14px; flex-wrap: wrap; align-items: stretch; margin-bottom: 14px; }",
+  "  .card { background: var(--surface-1); border: 1px solid var(--border); border-radius: 10px; padding: 18px 20px; }",
+  "  .hero { flex: 1 1 240px; display: flex; flex-direction: column; justify-content: center; }",
+  "  .hero .label { font-size: 13px; color: var(--text-2); }",
+  "  .hero .value { font-size: 52px; font-weight: 650; line-height: 1.1; letter-spacing: -0.5px; }",
+  "  .hero .sub { font-size: 13px; color: var(--muted); margin-top: 4px; }",
+  "  .tiles { flex: 2 1 420px; display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; }",
+  "  .tile { display: flex; flex-direction: column; justify-content: center; }",
+  "  .tile .label { font-size: 12.5px; color: var(--text-2); }",
+  "  .tile .value { font-size: 26px; font-weight: 650; margin-top: 2px; }",
+  "  .tile .sub { font-size: 12px; color: var(--muted); margin-top: 2px; }",
+  "  .chart { margin-bottom: 14px; }",
+  "  .chart h2, .tablecard h2 { font-size: 15px; font-weight: 650; margin: 0 0 2px; }",
+  "  .chart .sub, .tablecard .sub { font-size: 12.5px; color: var(--muted); margin: 0 0 14px; }",
+  "  .chart h2 { margin-bottom: 12px; }",
+  "  .barrow { display: grid; grid-template-columns: 1fr 64px; align-items: center; gap: 10px; padding: 3px 0; border-radius: 6px; }",
+  "  .barrow:hover { background: rgba(42,120,214,0.07); }",
+  "  .track { position: relative; height: 14px; }",
+  "  .bar { position: absolute; left: 0; top: 0; bottom: 0; background: var(--series-1); border-radius: 0 4px 4px 0; min-width: 2px; }",
+  "  .bar.other { opacity: 0.45; }",
+  "  .barrow .val { font-size: 12.5px; color: var(--text-2); font-variant-numeric: tabular-nums; }",
+  "  .axisline { border-left: 1px solid var(--baseline); position: absolute; top: 0; bottom: 0; left: 0; }",
+  "  .tablecard { padding: 18px 0 6px; margin-bottom: 14px; }",
+  "  .tablecard h2, .tablecard .sub { padding: 0 20px; }",
+  "  table { width: 100%; border-collapse: collapse; font-size: 13px; }",
+  "  th { text-align: left; font-weight: 600; color: var(--muted); font-size: 11.5px; text-transform: uppercase; letter-spacing: 0.04em; padding: 8px 10px; border-bottom: 1px solid var(--grid); white-space: nowrap; }",
+  "  td { padding: 8px 10px; border-bottom: 1px solid var(--grid); vertical-align: top; }",
+  "  tr:last-child td { border-bottom: none; }",
+  "  tbody tr:hover { background: rgba(42,120,214,0.05); }",
+  "  td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; }",
+  "  td.bname { font-weight: 600; white-space: nowrap; }",
+  "  td.bname .proj { display: block; font-weight: 400; font-size: 11.5px; color: var(--muted); }",
+  "  td.contents { color: var(--text-2); font-size: 12.5px; max-width: 300px; }",
+  "  td.contents .note { display: block; color: var(--muted); font-size: 12px; margin-top: 2px; }",
+  "  .chip { display: inline-flex; align-items: center; gap: 5px; font-size: 11.5px; font-weight: 600; padding: 2px 8px; border-radius: 999px; white-space: nowrap; }",
+  "  .chip.keep { background: var(--chip-keep-bg); }",
+  "  .chip.review { background: var(--chip-review-bg); }",
+  "  .chip.disp { background: var(--chip-disp-bg); color: var(--text-2); }",
+  "  .chip .dot { width: 7px; height: 7px; border-radius: 50%; }",
+  "  .chip.keep .dot { background: var(--good); }",
+  "  .chip.review .dot { background: var(--warn); }",
+  "  .chip.disp .dot { background: var(--muted); }",
+  "  .foot { color: var(--muted); font-size: 12px; margin-top: 18px; }",
+  "  .firstcol { padding-left: 20px; }",
+  "  .lastcol { padding-right: 20px; }",
+  "  .page { display: none; }",
+  "  .page.active { display: block; }",
+  "  tr.rowlink { cursor: pointer; }",
+  "  .chev { color: var(--muted); font-weight: 400; margin-left: 6px; }",
+  "  .pagehead { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; margin-bottom: 2px; }",
+  "  .backbtn { display: inline-flex; align-items: center; justify-content: center; width: 34px; height: 34px; border: 1px solid var(--border); border-radius: 9px; background: var(--surface-1); color: var(--text-2); text-decoration: none; font-size: 17px; line-height: 1; flex: 0 0 auto; }",
+  "  .backbtn:hover { color: var(--text-1); border-color: var(--baseline); }",
+  "  .tiles4 { display: grid; grid-template-columns: repeat(4, 1fr); gap: 14px; margin-bottom: 14px; }",
+  "  @media (max-width: 760px) { .tiles4 { grid-template-columns: repeat(2, 1fr); } .tiles { grid-template-columns: 1fr; } }",
+  "  td.key { font-size: 12.5px; color: var(--text-2); max-width: 420px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }",
+  "  .crumb { font-size: 13px; color: var(--muted); margin-bottom: 14px; }",
+  "  .crumb a { color: var(--text-2); text-decoration: none; }",
+  "  .crumb a:hover { color: var(--text-1); }",
+  "  .searchwrap { position: relative; max-width: 460px; margin: -12px 0 18px; }",
+  "  .search { width: 100%; padding: 9px 12px; font: inherit; font-size: 14px; color: var(--text-1); background: var(--surface-1); border: 1px solid var(--border); border-radius: 9px; outline: none; }",
+  "  .search:focus { border-color: var(--series-1); }",
+  "  .search::placeholder { color: var(--muted); }",
+  "  .qresults { display: none; position: absolute; top: calc(100% + 6px); left: 0; right: 0; background: var(--surface-1); border: 1px solid var(--border); border-radius: 10px; box-shadow: 0 8px 24px rgba(0,0,0,0.18); max-height: 340px; overflow-y: auto; z-index: 20; }",
+  "  .qitem { display: flex; justify-content: space-between; gap: 12px; padding: 8px 12px; cursor: pointer; font-size: 13px; }",
+  "  .qitem:hover { background: rgba(42,120,214,0.08); }",
+  "  .qitem strong { font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }",
+  "  .qitem span { color: var(--muted); white-space: nowrap; }",
+  "  tr.hit td { background: rgba(42,120,214,0.18); }",
+  "  .viztip { position: fixed; z-index: 10; background: var(--surface-1); border: 1px solid var(--border); border-radius: 6px; padding: 5px 9px; font-size: 12.5px; color: var(--text-1); pointer-events: none; box-shadow: 0 2px 10px rgba(0,0,0,0.15); display: none; white-space: nowrap; }",
+  "  .about { font-size: 13.5px; color: var(--text-2); margin: 0; }",
+].join("\n");
+
+// Plain-string scripts (no template interpolation anywhere near user data).
+const SCRIPT = [
+  "<script>",
+  "  function route() {",
+  '    var h = location.hash.slice(1);',
+  '    var target = h ? "page-" + h : "page-main";',
+  '    var pages = document.querySelectorAll(".page");',
+  "    var found = false;",
+  "    pages.forEach(function (p) { if (p.id === target) found = true; });",
+  '    if (!found) target = "page-main";',
+  '    pages.forEach(function (p) { p.classList.toggle("active", p.id === target); });',
+  "    window.scrollTo(0, 0);",
+  "  }",
+  '  window.addEventListener("hashchange", route);',
+  "  route();",
+  '  var tip = document.createElement("div");',
+  '  tip.className = "viztip";',
+  "  document.body.appendChild(tip);",
+  '  document.querySelectorAll(".barrow[data-label]").forEach(function (row) {',
+  '    row.addEventListener("mousemove", function (e) {',
+  '      tip.textContent = row.dataset.label + "  \\u00b7  " + row.dataset.val;',
+  '      tip.style.display = "block";',
+  "      var x = Math.min(e.clientX + 14, window.innerWidth - tip.offsetWidth - 8);",
+  '      tip.style.left = x + "px";',
+  '      tip.style.top = (e.clientY + 14) + "px";',
+  "    });",
+  '    row.addEventListener("mouseleave", function () { tip.style.display = "none"; });',
+  "  });",
+  "  (function () {",
+  '    var q = document.getElementById("q"), qr = document.getElementById("qr");',
+  "    if (!q) return;",
+  "    var idx = [], seen = {};",
+  '    document.querySelectorAll(".page").forEach(function (pg) {',
+  '      var h = pg.querySelector("h1");',
+  "      var title = h ? h.textContent.trim() : pg.id;",
+  '      if (pg.id === "page-main") title = "All buckets";',
+  '      var hash = pg.id === "page-main" ? "" : pg.id.slice(5);',
+  '      pg.querySelectorAll("td.bname, td.key").forEach(function (td) {',
+  '        var t = td.childNodes[0] ? td.childNodes[0].textContent.trim() : "";',
+  "        if (!t) return;",
+  '        var k = t + "|" + pg.id;',
+  "        if (seen[k]) return;",
+  "        seen[k] = 1;",
+  "        idx.push({ t: t, l: t.toLowerCase(), hash: hash, title: title, row: td.parentElement });",
+  "      });",
+  "    });",
+  "    var cur = [];",
+  "    function go(e) {",
+  "      location.hash = e.hash;",
+  '      qr.style.display = "none";',
+  "      setTimeout(function () {",
+  '        e.row.classList.add("hit");',
+  '        e.row.scrollIntoView({ block: "center" });',
+  '        setTimeout(function () { e.row.classList.remove("hit"); }, 1800);',
+  "      }, 60);",
+  "    }",
+  "    function render(list) {",
+  '      qr.innerHTML = "";',
+  "      list.slice(0, 20).forEach(function (e) {",
+  '        var d = document.createElement("div");',
+  '        d.className = "qitem";',
+  '        var s = document.createElement("strong"); s.textContent = e.t;',
+  '        var c = document.createElement("span"); c.textContent = e.title;',
+  "        d.appendChild(s); d.appendChild(c);",
+  '        d.addEventListener("mousedown", function (ev) { ev.preventDefault(); go(e); });',
+  "        qr.appendChild(d);",
+  "      });",
+  '      qr.style.display = list.length ? "block" : "none";',
+  "    }",
+  '    q.addEventListener("input", function () {',
+  "      var v = q.value.trim().toLowerCase();",
+  '      if (v.length < 2) { qr.style.display = "none"; cur = []; return; }',
+  "      var pre = [], sub = [];",
+  "      for (var i = 0; i < idx.length; i++) {",
+  "        var p = idx[i].l.indexOf(v);",
+  "        if (p === 0) pre.push(idx[i]); else if (p > 0) sub.push(idx[i]);",
+  "      }",
+  "      cur = pre.concat(sub);",
+  "      render(cur);",
+  "    });",
+  '    q.addEventListener("keydown", function (ev) {',
+  '      if (ev.key === "Enter" && cur.length) go(cur[0]);',
+  '      if (ev.key === "Escape") { q.value = ""; qr.style.display = "none"; }',
+  "    });",
+  '    document.addEventListener("click", function (ev) {',
+  '      if (!ev.target.closest(".searchwrap")) qr.style.display = "none";',
+  "    });",
+  "  })();",
+  "</script>",
+].join("\n");
+
+/**
+ * @param results   array of serialized bucket sweeps ({bucket,n,b,largest,prefixes})
+ * @param stats     Map bucket -> {cwObjects, classes, estMonthly}
+ * @param notes     object bucket -> {verdict, note, project} (optional)
+ * @param account   AWS account id string
+ */
+function render({ results, stats, notes = {}, account = "" }) {
+  const now = new Date();
+  const thisYear = String(now.getFullYear());
+  const genDate = MONTHS[now.getMonth() + 1] + " " + now.getDate() + ", " + now.getFullYear();
+
+  const st = (b) => stats.get(b) || { cwObjects: 0, classes: {}, estMonthly: 0 };
+  const order = [...results].sort((a, c) => st(c.bucket).estMonthly - st(a.bucket).estMonthly || c.b - a.b);
+
+  // slugs
+  const slugs = new Map();
+  const used = new Set();
+  for (const r of order) {
+    let s = r.bucket.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").slice(0, 50);
+    while (used.has(s)) s += "x";
+    used.add(s);
+    slugs.set(r.bucket, s);
+  }
+
+  const totalN = order.reduce((a, r) => a + r.n, 0);
+  const totalB = order.reduce((a, r) => a + r.b, 0);
+  const totalMo = order.reduce((a, r) => a + st(r.bucket).estMonthly, 0);
+  const regions = new Set(order.map((r) => r.region).filter(Boolean));
+  const coldB = order.reduce((a, r) => {
+    const c = st(r.bucket).classes;
+    return a + (((c.GlacierInstantRetrievalStorage || 0) + (c.GlacierStorage || 0) + (c.DeepArchiveStorage || 0)) * 1024 ** 3);
+  }, 0);
+  const hiddenBuckets = order.filter((r) => {
+    const h = st(r.bucket).cwObjects - r.n;
+    return h > 1000 && h > r.n * 0.01;
+  });
+
+  const anyVerdict = order.some((r) => notes[r.bucket] && notes[r.bucket].verdict);
+  const pages = [];
+
+  // -------------------------------------------------------------- main page
+  let rows = "";
+  for (const r of order) {
+    const a = notes[r.bucket] || {};
+    const slug = "b-" + slugs.get(r.bucket);
+    const prefs = r.prefixes.slice(0, 6).map((p) => esc(p.p));
+    let contents = prefs.length ? prefs.join(" · ") : "empty";
+    if (r.prefixes.length > 6) contents += " and " + (r.prefixes.length - 6) + " more";
+    const noteh = a.note ? '<span class="note">' + esc(a.note) + "</span>" : "";
+    rows +=
+      '<tr class="rowlink" onclick="location.hash=\'' + slug + '\'">' +
+      '<td class="bname firstcol">' + esc(r.bucket) + '<span class="chev">›</span>' +
+      '<span class="proj">' + esc(a.project || r.region || "") + "</span></td>" +
+      (anyVerdict ? "<td>" + chip(a.verdict) + "</td>" : "") +
+      '<td class="num">' + fmtB(r.b) + '</td><td class="num">' + fmtN(r.n) + '</td><td class="num">' + fmtUsd(st(r.bucket).estMonthly) + "</td>" +
+      '<td class="contents lastcol">' + contents + noteh + "</td></tr>";
+  }
+
+  let chartCard = "";
+  const chartItems = order.filter((r) => st(r.bucket).estMonthly >= 0.01).slice(0, 12);
+  if (chartItems.length >= 2) {
+    const maxu = st(chartItems[0].bucket).estMonthly;
+    const otherU = totalMo - chartItems.reduce((a, r) => a + st(r.bucket).estMonthly, 0);
+    let bars = "";
+    for (const r of chartItems) {
+      const u = st(r.bucket).estMonthly;
+      bars +=
+        '<div class="barrow" data-label="' + esc(r.bucket) + '" data-val="$' + u.toFixed(2) + '/mo"><div class="track">' +
+        '<div class="bar" style="width:' + ((u / maxu) * 100).toFixed(1) + '%"></div></div><div class="val">$' + u.toFixed(2) + "</div></div>";
+    }
+    if (otherU > 0.005) {
+      bars +=
+        '<div class="barrow" data-label="' + (order.length - chartItems.length) + ' more buckets" data-val="$' + otherU.toFixed(2) + '/mo"><div class="track">' +
+        '<div class="bar other" style="width:' + ((otherU / maxu) * 100).toFixed(1) + '%"></div></div><div class="val">$' + otherU.toFixed(2) + "</div></div>";
+    }
+    chartCard =
+      '<div class="card chart"><h2>Monthly cost by bucket</h2>' +
+      '<div style="position:relative;"><div class="axisline" style="left:0;"></div>' + bars + "</div></div>";
+  }
+
+  const hero = totalMo > 0
+    ? '<div class="card hero"><div class="label">S3 storage cost</div>' +
+      '<div class="value">$' + (totalMo / 30).toFixed(2) + '<span style="font-size:22px;color:var(--text-2);font-weight:500;">/day</span></div>' +
+      '<div class="sub">$' + totalMo.toFixed(2) + " per month, estimated at list prices</div></div>"
+    : '<div class="card hero"><div class="label">Stored</div>' +
+      '<div class="value">' + fmtB(totalB) + "</div>" +
+      '<div class="sub">across ' + order.length + " buckets</div></div>";
+
+  const storedTile = totalB > 0 && coldB > 0
+    ? Math.round((coldB / totalB) * 100) + "% in cold storage classes"
+    : "all storage classes";
+  const objectsSub = hiddenBuckets.length
+    ? hiddenBuckets.length + " bucket" + (hiddenBuckets.length > 1 ? "s" : "") + " also hide old versions"
+    : "current versions";
+
+  pages.push(
+    '<div id="page-main" class="page">' +
+    "<h1>Bucket List</h1>" +
+    '<div class="meta">Lightweight search for S3</div>' +
+    '<div class="searchwrap"><input id="q" class="search" type="search" placeholder="Search buckets, folders, files" autocomplete="off"><div id="qr" class="qresults"></div></div>' +
+    '<div class="toprow">' + hero +
+    '<div class="tiles">' +
+    '<div class="card tile"><div class="label">Stored</div><div class="value">' + fmtB(totalB) + '</div><div class="sub">' + storedTile + "</div></div>" +
+    '<div class="card tile"><div class="label">Objects</div><div class="value">' + (totalN >= 1e6 ? (totalN / 1e6).toFixed(1) + "M" : fmtN(totalN)) + '</div><div class="sub">' + objectsSub + "</div></div>" +
+    '<div class="card tile"><div class="label">Buckets</div><div class="value">' + order.length + '</div><div class="sub">' +
+    (regions.size > 1 ? "across " + regions.size + " regions" : [...regions][0] || "") + "</div></div>" +
+    "</div></div>" +
+    chartCard +
+    '<div class="card tablecard"><h2>All ' + order.length + " buckets</h2>" +
+    '<p class="sub">Every row opens a drill-down. Sorted by cost.</p>' +
+    '<table><thead><tr><th class="firstcol">Bucket</th>' + (anyVerdict ? "<th>Verdict</th>" : "") +
+    '<th class="num">Size</th><th class="num">Objects</th><th class="num">$/mo</th><th class="lastcol">Contents</th></tr></thead>' +
+    "<tbody>" + rows + "</tbody></table></div>" +
+    '<div class="foot">Full object enumeration via the AWS CLI · account ' + esc(account) + " · " + genDate +
+    " · storage only at us-east-1 list prices, an estimate; request and transfer charges excluded.</div>" +
+    "</div>"
+  );
+
+  // ------------------------------------------------- bucket + folder pages
+  for (const r of order) {
+    const a = notes[r.bucket] || {};
+    const slug = "b-" + slugs.get(r.bucket);
+    const bst = st(r.bucket);
+    let lastW = "";
+    let lastP = "";
+    for (const p of r.prefixes) {
+      if (p.w > lastW) {
+        lastW = p.w;
+        lastP = p.p;
+      }
+    }
+    const topShare = r.b > 0 && r.prefixes.length
+      ? Math.round((r.prefixes[0].b / r.b) * 100) + "% under " + esc(r.prefixes[0].p)
+      : "empty";
+
+    let prows = "";
+    r.prefixes.forEach((p, i) => {
+      const hasKids = !!(p.c && p.c.length);
+      const pid = "p-" + slugs.get(r.bucket) + "-" + i;
+      const click = hasKids ? ' class="rowlink" onclick="location.hash=\'' + pid + '\'"' : "";
+      const chev = hasKids ? '<span class="chev">›</span>' : "";
+      const fams = p.f || [];
+      const famtxt = fams.length && fams[0][1] > 2 ? " — " + esc(fams[0][0]) + " ×" + fmtN(fams[0][1]) : "";
+      prows +=
+        "<tr" + click + '><td class="bname firstcol">' + esc(p.p) + chev + "</td>" +
+        '<td class="num">' + fmtN(p.n) + '</td><td class="num">' + fmtB(p.b) + "</td>" +
+        "<td>" + fmtWin(p.o, p.w, thisYear) + "</td>" +
+        '<td class="contents lastcol">' + mostly(p) + famtxt + "</td></tr>";
+    });
+
+    let lrows = "";
+    for (const [key, sz, d] of r.largest.slice(0, 10)) {
+      lrows += '<tr><td class="key firstcol">' + esc(key) + '</td><td class="num">' + fmtB(sz) + '</td><td class="num lastcol">' + fmtD(d, thisYear) + "</td></tr>";
+    }
+    const largestCard = lrows
+      ? '<div class="card tablecard"><h2>Largest objects</h2>' +
+        '<table><thead><tr><th class="firstcol">Key</th><th class="num">Size</th><th class="num lastcol">Modified</th></tr></thead>' +
+        "<tbody>" + lrows + "</tbody></table></div>"
+      : "";
+
+    const hidden = bst.cwObjects - r.n;
+    let about = a.note ? esc(a.note) : "";
+    if (hidden > 1000 && hidden > r.n * 0.01) {
+      about += (about ? " " : "") +
+        "CloudWatch counts about " + fmtN(hidden) + " more objects than the listing shows, likely old versions kept by bucket versioning; a lifecycle rule expiring noncurrent versions would reclaim that storage.";
+    }
+    const aboutCard = about ? '<div class="card chart"><h2>About</h2><p class="about">' + about + "</p></div>" : "";
+
+    const tiles =
+      '<div class="tiles4">' +
+      '<div class="card tile"><div class="label">Stored</div><div class="value">' + fmtB(r.b) + '</div><div class="sub">' + topShare + "</div></div>" +
+      '<div class="card tile"><div class="label">Objects</div><div class="value">' + fmtN(r.n) + '</div><div class="sub">' + r.prefixes.length + " top-level folders</div></div>" +
+      '<div class="card tile"><div class="label">Cost</div><div class="value">$' + fmtUsd(bst.estMonthly) + '<span style="font-size:15px;color:var(--text-2);font-weight:500;">/mo</span></div><div class="sub">storage, estimated</div></div>' +
+      '<div class="card tile"><div class="label">Last write</div><div class="value">' + (fmtD(lastW, thisYear) || "–") + '</div><div class="sub">' + (esc(lastP) || "no objects") + "</div></div>" +
+      "</div>";
+
+    const ptable = prows
+      ? '<div class="card tablecard"><h2>By folder</h2><p class="sub">Sorted by size. Activity is the first-to-last write window.</p>' +
+        '<table><thead><tr><th class="firstcol">Folder</th><th class="num">Objects</th><th class="num">Size</th><th>Activity</th><th class="lastcol">Mostly</th></tr></thead>' +
+        "<tbody>" + prows + "</tbody></table></div>"
+      : '<div class="card chart"><p class="about">Empty bucket.</p></div>';
+
+    pages.push(
+      '<div id="page-' + slug + '" class="page">' +
+      '<div class="crumb"><a href="#">All buckets</a> › ' + esc(r.bucket) + "</div>" +
+      '<div class="pagehead"><a class="backbtn" href="#" aria-label="Back">←</a><h1>' + esc(r.bucket) + "</h1>" + (anyVerdict ? chip(a.verdict) : "") + "</div>" +
+      '<div class="meta">' + esc(r.region || "") + (a.project ? " · " + esc(a.project) : "") + "</div>" +
+      tiles + aboutCard + ptable + largestCard +
+      '<div class="foot">Full object enumeration via live S3 listing · nothing modified.</div>' +
+      "</div>"
+    );
+
+    // folder pages
+    r.prefixes.forEach((p, i) => {
+      if (!p.c || !p.c.length) return;
+      const pid = "p-" + slugs.get(r.bucket) + "-" + i;
+      let crows = "";
+      for (const k of p.c) {
+        crows +=
+          '<tr><td class="bname firstcol">' + esc(k.p) + "</td>" +
+          '<td class="num">' + fmtN(k.n) + '</td><td class="num">' + fmtB(k.b) + "</td>" +
+          "<td>" + fmtWin(k.o, k.w, thisYear) + "</td>" +
+          '<td class="contents lastcol">' + mostly(k) + "</td></tr>";
+      }
+      let fcard = "";
+      if (p.f && p.f.length) {
+        let frows = "";
+        for (const [pat, cnt, bb] of p.f.slice(0, 8)) {
+          frows += '<tr><td class="key firstcol">' + esc(pat) + '</td><td class="num">' + fmtN(cnt) + '</td><td class="num lastcol">' + fmtB(bb) + "</td></tr>";
+        }
+        fcard =
+          '<div class="card tablecard"><h2>Common file patterns</h2>' +
+          '<p class="sub"># stands in for any run of digits or hex, so one row is a whole family.</p>' +
+          '<table><thead><tr><th class="firstcol">Pattern</th><th class="num">Files</th><th class="num lastcol">Size</th></tr></thead>' +
+          "<tbody>" + frows + "</tbody></table></div>";
+      }
+      pages.push(
+        '<div id="page-' + pid + '" class="page">' +
+        '<div class="crumb"><a href="#">All buckets</a> › <a href="#' + slug + '">' + esc(r.bucket) + "</a> › " + esc(p.p) + "</div>" +
+        '<div class="pagehead"><a class="backbtn" href="#' + slug + '" aria-label="Back">←</a><h1>' + esc(p.p) + "</h1></div>" +
+        '<div class="meta">' + esc(r.bucket) + " · " + fmtN(p.n) + " objects · " + fmtB(p.b) + " · " + fmtWin(p.o, p.w, thisYear) + "</div>" +
+        '<div class="card tablecard"><h2>Folders</h2><p class="sub">Sorted by size.</p>' +
+        '<table><thead><tr><th class="firstcol">Folder</th><th class="num">Objects</th><th class="num">Size</th><th>Activity</th><th class="lastcol">Mostly</th></tr></thead>' +
+        "<tbody>" + crows + "</tbody></table></div>" + fcard +
+        '<div class="foot">Aggregated from the full object listing.</div>' +
+        "</div>"
+      );
+    });
+  }
+
+  return (
+    "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n" +
+    '<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
+    "<title>Bucket List</title>\n<style>\n" + CSS_VARS + "\n" + CSS + "\n</style>\n</head>\n<body>\n" +
+    '<div class="wrap">\n' + pages.join("\n") + "\n</div>\n" + SCRIPT + "\n</body>\n</html>\n"
+  );
+}
+
+module.exports = { render };

package/lib/sweep.js

@@ -0,0 +1,289 @@
+"use strict";
+// Discovery, cost estimation, and the recursive sharded sweep.
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { run, streamLs } = require("./aws");
+
+// $/GB-month at us-east-1 list prices, keyed by CloudWatch StorageType.
+// Prices vary by region and change over time; everything derived from these
+// is labeled an estimate in the output.
+const STORAGE_PRICES = {
+  StandardStorage: 0.023,
+  StandardIAStorage: 0.0125,
+  OneZoneIAStorage: 0.01,
+  GlacierInstantRetrievalStorage: 0.004,
+  GlacierStorage: 0.0036,
+  DeepArchiveStorage: 0.00099,
+  IntelligentTieringFAStorage: 0.023,
+  IntelligentTieringIAStorage: 0.0125,
+};
+
+// ---------------------------------------------------------------- discovery
+
+async function discoverBuckets(onlyNames) {
+  const res = await run(["s3api", "list-buckets"]);
+  let names = (res.Buckets || []).map((b) => b.Name);
+  if (onlyNames && onlyNames.length) {
+    const want = new Set(onlyNames);
+    const have = new Set(names);
+    for (const n of onlyNames) {
+      if (!have.has(n)) throw new Error(`bucket not found in this account: ${n}`);
+    }
+    names = names.filter((n) => want.has(n));
+  }
+  const buckets = [];
+  const skipped = [];
+  await Promise.all(
+    names.map(async (name) => {
+      try {
+        const lc = await run(["s3api", "get-bucket-location", "--bucket", name]);
+        let region = lc.LocationConstraint || "us-east-1";
+        if (region === "EU") region = "eu-west-1";
+        buckets.push({ name, region });
+      } catch (e) {
+        skipped.push({ name, reason: e.message });
+      }
+    })
+  );
+  buckets.sort((a, b) => a.name.localeCompare(b.name));
+  return { buckets, skipped };
+}
+
+// ---------------------------------------------------------------- estimate
+
+async function estimate(buckets) {
+  // CloudWatch daily storage metrics, batched per region, <=50 buckets/call.
+  const byRegion = new Map();
+  for (const b of buckets) {
+    if (!byRegion.has(b.region)) byRegion.set(b.region, []);
+    byRegion.get(b.region).push(b.name);
+  }
+  const stats = new Map(); // name -> {cwObjects, classes:{type:GB}, estMonthly}
+  for (const b of buckets) stats.set(b.name, { cwObjects: 0, classes: {}, estMonthly: 0 });
+
+  const end = new Date();
+  const start = new Date(end.getTime() - 3 * 86400 * 1000);
+  const types = Object.keys(STORAGE_PRICES);
+
+  for (const [region, names] of byRegion) {
+    for (let i = 0; i < names.length; i += 50) {
+      const chunk = names.slice(i, i + 50);
+      const queries = [];
+      chunk.forEach((name, bi) => {
+        queries.push({
+          Id: `c${bi}`,
+          MetricStat: {
+            Metric: {
+              Namespace: "AWS/S3",
+              MetricName: "NumberOfObjects",
+              Dimensions: [
+                { Name: "BucketName", Value: name },
+                { Name: "StorageType", Value: "AllStorageTypes" },
+              ],
+            },
+            Period: 86400,
+            Stat: "Average",
+          },
+          ReturnData: true,
+        });
+        types.forEach((t, ti) => {
+          queries.push({
+            Id: `s${bi}_${ti}`,
+            MetricStat: {
+              Metric: {
+                Namespace: "AWS/S3",
+                MetricName: "BucketSizeBytes",
+                Dimensions: [
+                  { Name: "BucketName", Value: name },
+                  { Name: "StorageType", Value: t },
+                ],
+              },
+              Period: 86400,
+              Stat: "Average",
+            },
+            ReturnData: true,
+          });
+        });
+      });
+      const qfile = path.join(os.tmpdir(), `bucketlist-q-${process.pid}-${i}.json`);
+      fs.writeFileSync(qfile, JSON.stringify(queries));
+      try {
+        const res = await run(
+          [
+            "cloudwatch", "get-metric-data",
+            "--metric-data-queries", `file://${qfile}`,
+            "--start-time", start.toISOString(),
+            "--end-time", end.toISOString(),
+            "--scan-by", "TimestampDescending",
+          ],
+          { region }
+        );
+        for (const m of res.MetricDataResults || []) {
+          if (!m.Values || !m.Values.length) continue;
+          const v = m.Values[0];
+          const mm = /^c(\d+)$/.exec(m.Id) || /^s(\d+)_(\d+)$/.exec(m.Id);
+          if (!mm) continue;
+          const st = stats.get(chunk[parseInt(mm[1], 10)]);
+          if (m.Id.startsWith("c")) {
+            st.cwObjects = Math.round(v);
+          } else {
+            const t = types[parseInt(mm[2], 10)];
+            const gb = v / 1024 ** 3;
+            if (gb > 0.001) {
+              st.classes[t] = gb;
+              st.estMonthly += gb * STORAGE_PRICES[t];
+            }
+          }
+        }
+      } catch (e) {
+        // CloudWatch denied or absent: the sweep still works, costs show as 0.
+      } finally {
+        fs.unlinkSync(qfile);
+      }
+    }
+  }
+  return stats;
+}
+
+// ---------------------------------------------------------------- aggregator
+
+function newNode() {
+  return { n: 0, b: 0, o: "9999", w: "", ext: new Map(), fam: new Map(), c: new Map() };
+}
+
+function bump(node, size, lm, ext, pat) {
+  node.n++;
+  node.b += size;
+  if (lm < node.o) node.o = lm;
+  if (lm > node.w) node.w = lm;
+  node.ext.set(ext, (node.ext.get(ext) || 0) + size);
+  const f = node.fam.get(pat);
+  if (f) {
+    f[0]++;
+    f[1] += size;
+  } else {
+    node.fam.set(pat, [1, size]);
+  }
+  if (node.fam.size > 1200) {
+    const keep = [...node.fam.entries()].sort((a, b) => b[1][1] - a[1][1]).slice(0, 500);
+    node.fam = new Map(keep);
+  }
+}
+
+function newAgg() {
+  return { n: 0, b: 0, nodes: new Map(), largest: [] };
+}
+
+function aggAdd(agg, key, size, lm) {
+  agg.n++;
+  agg.b += size;
+  const parts = key.split("/");
+  const fn = parts[parts.length - 1];
+  const pat = fn.replace(/[0-9a-fA-F]{6,}/g, "#").replace(/\d+/g, "#").slice(0, 80);
+  const dot = fn.lastIndexOf(".");
+  const ext = dot > 0 && fn.length - dot <= 10 ? fn.slice(dot).toLowerCase() : "(none)";
+  const l1 = parts.length > 1 ? parts[0] + "/" : "(root)";
+  let n1 = agg.nodes.get(l1);
+  if (!n1) agg.nodes.set(l1, (n1 = newNode()));
+  bump(n1, size, lm, ext, pat);
+  if (parts.length > 2) {
+    const l2 = parts[0] + "/" + parts[1] + "/";
+    let n2 = n1.c.get(l2);
+    if (!n2) n1.c.set(l2, (n2 = newNode()));
+    bump(n2, size, lm, ext, pat);
+  }
+  agg.largest.push([size, key, lm]);
+  if (agg.largest.length > 400) {
+    agg.largest.sort((a, b) => b[0] - a[0]);
+    agg.largest.length = 12;
+  }
+}
+
+function serNode(name, node, withKids) {
+  const out = {
+    p: name,
+    n: node.n,
+    b: node.b,
+    o: node.o,
+    w: node.w,
+    x: [...node.ext.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3),
+    f: [...node.fam.entries()].sort((a, b) => b[1][1] - a[1][1]).slice(0, 6).map(([p, c]) => [p, c[0], c[1]]),
+  };
+  if (withKids && node.c.size) {
+    const kids = [...node.c.entries()].sort((a, b) => b[1].b - a[1].b);
+    out.c = kids.slice(0, 30).map(([k, v]) => serNode(k, v, false));
+    if (kids.length > 30) {
+      let rn = 0, rb = 0;
+      for (const [, v] of kids.slice(30)) {
+        rn += v.n;
+        rb += v.b;
+      }
+      out.c.push({ p: `(${kids.length - 30} more)`, n: rn, b: rb, o: "", w: "", x: [], f: [] });
+    }
+  }
+  return out;
+}
+
+function serialize(agg, bucket) {
+  agg.largest.sort((a, b) => b[0] - a[0]);
+  const prefs = [...agg.nodes.entries()].sort((a, b) => b[1].b - a[1].b);
+  return {
+    bucket,
+    n: agg.n,
+    b: agg.b,
+    largest: agg.largest.slice(0, 12).map(([s, k, d]) => [k, s, d]),
+    prefixes: prefs.slice(0, 40).map(([k, v]) => serNode(k, v, true)),
+  };
+}
+
+// ---------------------------------------------------------------- walker
+
+const SPLIT_DEPTH = 4; // below this, stream flat
+const KID_LIMIT = 1500; // folder explosion guard at the bucket root
+const KID_SPLIT_MAX = 64; // deeper levels: more folders than this means a
+// partitioned layout (dt=2025-03-21/ style); one stream beats 10,000 spawns
+const PAGE_CAP = 50000; // max entries to hold from one delimiter listing
+
+async function walk(bucket, region, prefix, depth, agg) {
+  if (depth >= SPLIT_DEPTH) return flat(bucket, region, prefix, agg);
+  let res;
+  try {
+    res = await run(
+      [
+        "s3api", "list-objects-v2",
+        "--bucket", bucket,
+        "--prefix", prefix,
+        "--delimiter", "/",
+        "--max-items", String(PAGE_CAP),
+      ],
+      { region }
+    );
+  } catch (e) {
+    // fall back to a flat stream on any listing hiccup
+    return flat(bucket, region, prefix, agg);
+  }
+  const kids = (res.CommonPrefixes || []).map((p) => p.Prefix);
+  const kidCap = depth === 0 ? KID_LIMIT : KID_SPLIT_MAX;
+  if (res.NextToken || kids.length > kidCap) {
+    // too big or too many folders at this level: stream the whole subtree
+    // (nothing from this listing was merged, so no double counting)
+    return flat(bucket, region, prefix, agg);
+  }
+  for (const o of res.Contents || []) {
+    aggAdd(agg, o.Key, o.Size, String(o.LastModified).slice(0, 10));
+  }
+  await Promise.all(kids.map((k) => walk(bucket, region, k, depth + 1, agg)));
+}
+
+async function flat(bucket, region, prefix, agg) {
+  await streamLs(`s3://${bucket}/${prefix}`, region, (d, s, k) => aggAdd(agg, k, s, d));
+}
+
+async function sweepBucket(bucket, region) {
+  const agg = newAgg();
+  await walk(bucket, region, "", 0, agg);
+  return serialize(agg, bucket);
+}
+
+module.exports = { discoverBuckets, estimate, sweepBucket, STORAGE_PRICES };

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@nysgpt/bucket-list",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Bucket List \u2014 lightweight search for S3. One command sweeps every bucket in an AWS account into a single offline HTML file: drill-down by bucket and folder, object counts, storage-class costs, largest files, and instant search.",
+  "bin": {
+    "bucket-list": "bin/bucket-list.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "aws",
+    "s3",
+    "inventory",
+    "storage",
+    "cost",
+    "dashboard",
+    "cli",
+    "bucket",
+    "audit"
+  ],
+  "author": "Brendan Stanton <brendan@nysgpt.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nyd-user-1/bucket-list.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }