vaultburn 1.0.0__tar.gz

vaultburn-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VaultBurn
+
+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.

vaultburn-1.0.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: vaultburn
+Version: 1.0.0
+Summary: Offline SaaS spend auditor. CSV in → decision report out. VaultBurn discovers decisions; it never makes them.
+Author-email: VaultBurn <vaultburn@proton.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/neverlose-io/vaultburn
+Project-URL: Repository, https://github.com/neverlose-io/vaultburn
+Project-URL: Issues, https://github.com/neverlose-io/vaultburn/issues
+Keywords: saas,audit,csv,offline,spend,decision-support
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# VaultBurn
+
+Offline SaaS spend auditor. CSV in → decision report out.
+
+**VaultBurn discovers decisions. It never makes them.**
+
+## Install
+
+```bash
+pip install vaultburn
+```
+
+Use
+
+```bash
+vaultburn subs.csv              # text report
+vaultburn subs.csv --json r.json
+vaultburn --init                # generate template
+vaultburn --help                # full schema & philosophy
+```
+
+Schema
+
+Required: name, monthly_cost, seats, used_seats, last_used
+
+Optional: renew_date, category, critical, reason, replacement_group, cost_model
+
+cost_model
+
+· per_seat (default): monthly_cost is the price per seat
+· flat: monthly_cost is the total monthly price
+
+Signals
+
+· monthly_spend — Sum of all subscriptions
+· unused_seat_cost — Idle seats × seat cost
+· potentially_cancellable — used=0 AND stale AND not critical
+· duplicate_candidate — From user-declared replacement groups
+· renewals_7d — Subscriptions renewing within 7 days
+
+Verdicts
+
+· cancellable — used=0, stale, not critical
+· review — needs human attention
+· protected — critical, never suggested for cancellation
+· ignored — user marked replacement_group=ignore
+· ok — clean
+
+What it does NOT do
+
+· No cloud. No OAuth. No accounts. No telemetry.
+· No auto-cancel. No auto-keep. No cheapest-wins.
+· No Stripe (yet — will add only if 3 users request it).
+
+Philosophy
+
+VaultBurn discovers decisions. It never makes them.
+
+License
+
+MIT.

vaultburn-1.0.0/README.md

@@ -0,0 +1,61 @@
+# VaultBurn
+
+Offline SaaS spend auditor. CSV in → decision report out.
+
+**VaultBurn discovers decisions. It never makes them.**
+
+## Install
+
+```bash
+pip install vaultburn
+```
+
+Use
+
+```bash
+vaultburn subs.csv              # text report
+vaultburn subs.csv --json r.json
+vaultburn --init                # generate template
+vaultburn --help                # full schema & philosophy
+```
+
+Schema
+
+Required: name, monthly_cost, seats, used_seats, last_used
+
+Optional: renew_date, category, critical, reason, replacement_group, cost_model
+
+cost_model
+
+· per_seat (default): monthly_cost is the price per seat
+· flat: monthly_cost is the total monthly price
+
+Signals
+
+· monthly_spend — Sum of all subscriptions
+· unused_seat_cost — Idle seats × seat cost
+· potentially_cancellable — used=0 AND stale AND not critical
+· duplicate_candidate — From user-declared replacement groups
+· renewals_7d — Subscriptions renewing within 7 days
+
+Verdicts
+
+· cancellable — used=0, stale, not critical
+· review — needs human attention
+· protected — critical, never suggested for cancellation
+· ignored — user marked replacement_group=ignore
+· ok — clean
+
+What it does NOT do
+
+· No cloud. No OAuth. No accounts. No telemetry.
+· No auto-cancel. No auto-keep. No cheapest-wins.
+· No Stripe (yet — will add only if 3 users request it).
+
+Philosophy
+
+VaultBurn discovers decisions. It never makes them.
+
+License
+
+MIT.

vaultburn-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vaultburn"
+version = "1.0.0"
+description = "Offline SaaS spend auditor. CSV in → decision report out. VaultBurn discovers decisions; it never makes them."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "VaultBurn", email = "vaultburn@proton.me" }]
+keywords = ["saas", "audit", "csv", "offline", "spend", "decision-support"]
+dependencies = []
+
+[project.scripts]
+vaultburn = "vaultburn:main"
+
+[project.urls]
+Homepage = "https://github.com/neverlose-io/vaultburn"
+Repository = "https://github.com/neverlose-io/vaultburn"
+Issues = "https://github.com/neverlose-io/vaultburn/issues"
+
+[tool.setuptools]
+packages = ["vaultburn"]

vaultburn-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vaultburn-1.0.0/vaultburn/__init__.py

@@ -0,0 +1,440 @@
+# vaultburn.py — v1.0.0 | MIT | Python 3.9+
+"""Offline SaaS spend auditor.
+
+VaultBurn discovers decisions. It never makes them.
+No cloud. No OAuth. No telemetry. No auto-selection.
+"""
+import csv, json, sys, argparse, re
+from datetime import date, datetime
+from pathlib import Path
+from typing import Optional, List, Dict, Any, Tuple
+from decimal import Decimal, InvalidOperation
+
+VERSION = "1.0.0"
+DEFAULT_STALE_AFTER = 45
+DEFAULT_DUP_THRESHOLD = Decimal("20")
+RENEW_WINDOW = 7
+GROUP_RE = re.compile(r"^([a-zA-Z0-9_\-]+)(\*?)$")
+
+SCHEMA_REQUIRED = ["name", "monthly_cost", "seats", "used_seats", "last_used"]
+SCHEMA_OPTIONAL = ["renew_date", "category", "critical", "reason",
+                   "replacement_group", "cost_model"]
+
+TEMPLATE = (
+    "name,monthly_cost,cost_model,seats,used_seats,last_used,renew_date,"
+    "category,critical,reason,replacement_group\n"
+    "ChatGPT Team,150,flat,5,2,2026-09-20,2026-10-03,ai-assistant,false,,ai-1*\n"
+    "Claude Pro,20,per_seat,1,1,2026-09-25,2026-10-10,ai-assistant,false,,ai-1\n"
+    "Figma,45,per_seat,2,1,2026-09-01,2026-10-05,design,false,,\n"
+    "Notion,80,flat,4,4,2026-09-28,2026-11-15,docs,true,team-wiki,\n"
+    "AWS Support,100,flat,10,7,2026-09-30,2026-10-01,infrastructure,true,"
+    "regulatory-compliance,ignore\n"
+)
+
+HELP_EPILOG = """\
+INPUT SCHEMA (required columns):
+  name, monthly_cost, seats, used_seats, last_used
+OPTIONAL COLUMNS:
+  renew_date, category, critical, reason, replacement_group, cost_model
+
+cost_model (optional, default: per_seat):
+  flat       → monthly_cost = السعر الشهري الإجمالي للاشتراك
+  per_seat   → monthly_cost = السعر الشهري لمقعد واحد (يُضرب في seats)
+
+SIGNALS (conservative by default):
+  monthly_spend            sum of all monthly_cost (مُوحَّد)
+  unused_seat_cost         idle seats × seat cost (per cost_model)
+  potentially_cancellable  used=0 AND stale AND !critical
+  duplicate_candidate      same replacement_group, combined > threshold
+  renewals_7d              subscriptions renewing within 7 days
+
+DEFAULTS (not industry standards — override freely):
+  --stale-after 45         review threshold, not a policy
+  --duplicate-threshold 20 USD floor to suppress noise
+
+replacement_group VALUES:
+  ""         no claim of equivalence
+  "grp"      user-declared equivalence group → REVIEW
+  "grp*"     user-declared preferred candidate → USER-PREFERRED
+  "ignore"   excluded from duplicate analysis
+
+VERDICTS:
+  cancellable  used=0 AND stale AND !critical
+  review       needs human attention
+  protected    critical=true — never suggested for cancellation
+  ignored      replacement_group=ignore
+  ok           clean
+
+renewals_7d actionable = reported  →  fact, not recommendation
+
+PHILOSOPHY:
+  VaultBurn discovers decisions. It never makes them.
+  No auto-keep. No auto-cancel. No cheapest-wins.
+"""
+
+# ───────── Primitives ─────────
+
+def _dec(v: Any, d: Optional[Decimal] = None) -> Optional[Decimal]:
+    if v is None or str(v).strip() == "": return d
+    try: return Decimal(str(v).strip())
+    except InvalidOperation: return None
+
+def _int(v: Any) -> Optional[int]:
+    x = _dec(v); return None if x is None else int(x)
+
+def _bool(v: Any) -> bool:
+    return str(v).strip().lower() in ("true", "1", "yes", "y")
+
+def _date(s: str) -> Optional[date]:
+    if not s: return None
+    for fmt in ("%Y-%m-%d", "%d/%m/%Y", "%m/%d/%Y"):
+        try: return datetime.strptime(s.strip(), fmt).date()
+        except ValueError: continue
+    return None
+
+def _days_since(d: Optional[date]) -> Optional[int]:
+    return None if d is None else (date.today() - d).days
+
+def _days_until(d: Optional[date]) -> Optional[int]:
+    return None if d is None else (d - date.today()).days
+
+def _parse_group(raw: str) -> Tuple[Optional[str], bool, bool]:
+    s = (raw or "").strip()
+    if s == "": return None, False, False
+    if s.lower() == "ignore": return None, False, True
+    m = GROUP_RE.match(s)
+    if not m: return None, False, False
+    return m.group(1), m.group(2) == "*", False
+
+def _norm_rows(text: str) -> List[str]:
+    text = text.lstrip("\ufeff")
+    return [ln for ln in text.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+            if ln.strip()]
+
+# ───────── Row Parsing ─────────
+
+def parse_row(r: Dict[str, str], idx: int) -> Optional[Dict[str, Any]]:
+    name = (r.get("name") or "").strip()
+    if not name:
+        print(f"⚠️  row {idx}: name missing", file=sys.stderr); return None
+
+    cost = _dec(r.get("monthly_cost"))
+    if cost is None or cost < 0:
+        print(f"⚠️  row {idx} ({name}): monthly_cost invalid",
+              file=sys.stderr); return None
+
+    seats, used = _int(r.get("seats")), _int(r.get("used_seats"))
+    if seats is None or seats <= 0 or used is None or used < 0 or used > seats:
+        print(f"⚠️  row {idx} ({name}): seats/used_seats invalid",
+              file=sys.stderr); return None
+
+    last = _date(r.get("last_used", ""))
+    if last is None:
+        print(f"⚠️  row {idx} ({name}): last_used missing or unparseable",
+              file=sys.stderr); return None
+
+    # التعديل #1: cost_model اختياري، default=per_seat، صريح
+    model = (r.get("cost_model") or "per_seat").strip().lower()
+    if model not in ("flat", "per_seat"):
+        print(f"⚠️  row {idx} ({name}): cost_model must be flat or per_seat",
+              file=sys.stderr); return None
+
+    gid, preferred, ignored = _parse_group(r.get("replacement_group", ""))
+    return {
+        "name": name, "cost": cost, "model": model,
+        "seats": seats, "used": used,
+        "last_used": last,
+        "renew": _date(r.get("renew_date", "")),
+        "category": (r.get("category") or "").strip().lower() or None,
+        "critical": _bool(r.get("critical", "false")),
+        "reason": (r.get("reason") or "").strip() or None,
+        "group_id": gid, "group_preferred": preferred, "group_ignored": ignored,
+    }
+
+# ───────── Signals (reported / actionable) ─────────
+
+def _pair(reported: Decimal, actionable: Decimal) -> Dict[str, float]:
+    return {"reported": float(round(reported, 2)),
+            "actionable": float(round(actionable, 2))}
+
+def _unused_pair(row: Dict[str, Any]) -> Dict[str, float]:
+    """التعديل #1: يفرّق flat عن per_seat بشكل صريح."""
+    idle = row["seats"] - row["used"]
+    if idle <= 0: return _pair(Decimal(0), Decimal(0))
+    if row["model"] == "per_seat":
+        # monthly_cost = سعر المقعد الواحد
+        amt = row["cost"] * idle
+    else:
+        # flat = السعر الكلي، التوزيع نسبي
+        amt = (row["cost"] / row["seats"]) * idle
+    return _pair(amt, Decimal(0) if row["critical"] else amt)
+
+def _cancellable_pair(row: Dict[str, Any], stale_after: int) -> Dict[str, float]:
+    since = _days_since(row["last_used"])
+    stale = since is not None and since > stale_after
+    eligible = (row["used"] == 0 and stale and not row["critical"]
+                and not row["group_ignored"])
+    if eligible:
+        return _pair(row["cost"], row["cost"])
+    return _pair(Decimal(0), Decimal(0))
+
+def _renew_pair(row: Dict[str, Any]) -> Dict[str, float]:
+    until = _days_until(row["renew"])
+    if until is None or not (0 <= until <= RENEW_WINDOW):
+        return _pair(Decimal(0), Decimal(0))
+    return _pair(row["cost"], row["cost"])
+
+def classify(row: Dict[str, Any], stale_after: int) -> Dict[str, Any]:
+    idle = row["seats"] - row["used"]
+    since = _days_since(row["last_used"])
+    until = _days_until(row["renew"])
+    stale = since is not None and since > stale_after
+
+    reasons: List[str] = []
+    if row["reason"]: reasons.append(f"context: {row['reason']}")
+
+    cancellable = Decimal("0")
+    verdict = "ok"
+
+    # التعديل #2: protected حالة خامسة، ليست review
+    if row["group_ignored"]:
+        verdict = "ignored"
+        reasons.append("replacement_group=ignore - excluded from duplicate analysis")
+    elif row["critical"]:
+        verdict = "protected"
+        reasons.append("critical - never suggested for cancellation")
+    elif row["used"] == 0 and stale:
+        verdict = "cancellable"
+        cancellable = row["cost"]
+        reasons.append(f"no users - last used {since} days ago")
+    elif row["used"] == 0:
+        verdict = "review"
+        reasons.append(f"used_seats = 0 - last used {since} days ago")
+    elif stale:
+        verdict = "review"
+        reasons.append(f"last used {since} days ago - exceeds {stale_after}")
+    elif idle > 0:
+        verdict = "review"
+        reasons.append(f"{idle} idle seats")
+
+    if until is not None and 0 <= until <= RENEW_WINDOW:
+        reasons.append(f"renews in {until} days")
+
+    return {
+        "name": row["name"], "verdict": verdict,
+        "monthly_spend": float(row["cost"]),
+        "cost_model": row["model"],
+        "signals": {
+            "unused_seat_cost":        _unused_pair(row),
+            "potentially_cancellable": _pair(cancellable, cancellable),
+            "renewals_7d":             _renew_pair(row),
+        },
+        "idle_seats": idle,
+        "days_since_used": since,
+        "days_until_renew": until,
+        "category": row["category"],
+        "critical": row["critical"],
+        "reason": row["reason"],
+        "replacement_group": row["group_id"],
+        "user_preferred": row["group_preferred"],
+        "reasons": reasons,
+    }
+
+# ───────── Duplicate Detection ─────────
+
+def find_groups(rows: List[Dict[str, Any]],
+                threshold: Decimal) -> List[Dict[str, Any]]:
+    buckets: Dict[str, List[Dict[str, Any]]] = {}
+    for r in rows:
+        if r["group_ignored"] or not r["group_id"]: continue
+        buckets.setdefault(r["group_id"], []).append(r)
+
+    out = []
+    for gid, members in buckets.items():
+        if len(members) < 2: continue
+        combined = sum(m["cost"] for m in members)
+        if combined < threshold: continue
+        preferred = [m["name"] for m in members if m["group_preferred"]]
+        out.append({
+            "group_id": gid,
+            "candidates": [m["name"] for m in members],
+            "signals": {
+                "duplicate_candidate": _pair(combined, Decimal(0)),
+            },
+            "user_preferred": preferred or None,
+            "action": "USER-PREFERRED" if preferred else "REVIEW",
+            "note": ("explicit user preference - tool does not rank or choose"
+                     if preferred else "similarity signal - decision for the user"),
+        })
+    return sorted(out, key=lambda g: -g["signals"]["duplicate_candidate"]["reported"])
+
+# ───────── Analysis ─────────
+
+def _sum_signal(items: List[Dict[str, Any]], key: str) -> Dict[str, float]:
+    r = sum(i["signals"][key]["reported"] for i in items)
+    a = sum(i["signals"][key]["actionable"] for i in items)
+    return _pair(Decimal(str(r)), Decimal(str(a)))
+
+def analyze(rows: List[Dict[str, Any]], stale_after: int,
+            dup_threshold: Decimal) -> Dict[str, Any]:
+    items = [classify(r, stale_after) for r in rows]
+    groups = find_groups(rows, dup_threshold)
+    dup_reported = sum(g["signals"]["duplicate_candidate"]["reported"] for g in groups)
+
+    return {
+        "generated": date.today().isoformat(),
+        "version": VERSION,
+        "thresholds": {
+            "stale_after_days": stale_after,
+            "renew_window_days": RENEW_WINDOW,
+            "duplicate_threshold_usd": float(dup_threshold),
+        },
+        "totals": {
+            "monthly_spend": float(round(sum(i["monthly_spend"] for i in items), 2)),
+            "signals": {
+                "unused_seat_cost":        _sum_signal(items, "unused_seat_cost"),
+                "potentially_cancellable": _sum_signal(items, "potentially_cancellable"),
+                "duplicate_candidate":     _pair(Decimal(str(dup_reported)), Decimal(0)),
+                "renewals_7d":             _sum_signal(items, "renewals_7d"),
+            },
+        },
+        "counts": {
+            "cancellable": sum(1 for i in items if i["verdict"] == "cancellable"),
+            "review":      sum(1 for i in items if i["verdict"] == "review"),
+            "ok":          sum(1 for i in items if i["verdict"] == "ok"),
+            "protected":   sum(1 for i in items if i["verdict"] == "protected"),
+            "ignored":     sum(1 for i in items if i["verdict"] == "ignored"),
+        },
+        "items": sorted(items,
+                        key=lambda x: -x["signals"]["potentially_cancellable"]["reported"]),
+        "replacement_groups": groups,
+    }
+
+# ───────── Report ─────────
+
+def render(rep: Dict[str, Any]) -> None:
+    t, c, th = rep["totals"], rep["counts"], rep["thresholds"]
+    sig = t["signals"]
+    print(f"\n📋 VaultBurn v{VERSION} - {rep['generated']}")
+    print(f"   stale-after={th['stale_after_days']}d · "
+          f"renew-window={th['renew_window_days']}d · "
+          f"dup-threshold=${th['duplicate_threshold_usd']:.0f}")
+    print("─" * 72)
+    print(f"💰 Monthly spend                      : ${t['monthly_spend']:.2f}")
+    print(f"🪑 Idle seat cost    (reported / actionable): "
+          f"${sig['unused_seat_cost']['reported']:.2f} / "
+          f"${sig['unused_seat_cost']['actionable']:.2f}")
+    print(f"✂️  Cancellable       (reported / actionable): "
+          f"${sig['potentially_cancellable']['reported']:.2f} / "
+          f"${sig['potentially_cancellable']['actionable']:.2f}")
+    print(f"🔁 Duplicate candid. (reported / actionable): "
+          f"${sig['duplicate_candidate']['reported']:.2f} / "
+          f"${sig['duplicate_candidate']['actionable']:.2f}")
+    print(f"⏰ Renewals in 7 days (reported / actionable): "
+          f"${sig['renewals_7d']['reported']:.2f} / "
+          f"${sig['renewals_7d']['actionable']:.2f}")
+    print(f"🔢 {c['cancellable']} cancellable · {c['review']} review · "
+          f"{c['ok']} ok · {c['protected']} protected · {c['ignored']} ignored")
+    print("─" * 72)
+
+    for i in rep["items"]:
+        if i["verdict"] == "ok" and not i["reasons"]: continue
+        icon = {"cancellable": "🔴", "review": "🟡", "ok": "🟢",
+                "protected": "🛡️", "ignored": "⚪"}[i["verdict"]]
+        line = f"{icon} {i['name']:<20} monthly ${i['monthly_spend']:.2f}"
+        u = i["signals"]["unused_seat_cost"]
+        if u["reported"] > 0:
+            line += f" - idle ${u['reported']:.2f}"
+        print(line)
+        for r in i["reasons"]: print(f"     • {r}")
+
+    if rep["replacement_groups"]:
+        print("─" * 72)
+        print("⚠️  REPLACEMENT GROUPS - user-declared similarity, not a decision:")
+        for g in rep["replacement_groups"]:
+            d = g["signals"]["duplicate_candidate"]
+            print(f"   group: {g['group_id']}  →  {g['action']}")
+            print(f"   candidates: {', '.join(g['candidates'])}")
+            print(f"   combined: ${d['reported']:.2f} (actionable: ${d['actionable']:.2f})")
+            if g["user_preferred"]:
+                print(f"   user_preferred: {', '.join(g['user_preferred'])}")
+            print(f"   note: {g['note']}")
+
+    print("─" * 72)
+    print("ℹ️  VaultBurn discovers decisions. It never makes them.")
+
+# ───────── CLI ─────────
+
+def cmd_init(path: Path) -> None:
+    if path.exists():
+        print(f"❌ {path} already exists"); sys.exit(1)
+    path.write_text(TEMPLATE, encoding="utf-8")
+    print(f"✅ Template: {path}\n   Edit it, then: vaultburn {path}")
+
+def load(path: Path) -> List[Dict[str, Any]]:
+    if not path.exists():
+        print(f"❌ File not found: {path}", file=sys.stderr); sys.exit(1)
+    text = path.read_text(encoding="utf-8-sig", errors="replace")
+    lines = _norm_rows(text)
+    if not lines:
+        print("❌ File is empty", file=sys.stderr); sys.exit(1)
+
+    header = [h.strip().lower() for h in next(csv.reader([lines[0]]))]
+    missing = [c for c in SCHEMA_REQUIRED if c not in header]
+    if missing:
+        print(f"❌ Missing columns: {', '.join(missing)}", file=sys.stderr)
+        print(f"   Required: {', '.join(SCHEMA_REQUIRED)}", file=sys.stderr)
+        sys.exit(2)
+
+    reader = csv.DictReader(lines)
+    parsed = [parse_row(r, i) for i, r in enumerate(reader, 2)]
+    rows = [r for r in parsed if r]
+    if not rows:
+        print("❌ No valid rows", file=sys.stderr); sys.exit(1)
+    return rows
+
+def main() -> None:
+    p = argparse.ArgumentParser(
+        prog="vaultburn",
+        description="Offline SaaS spend auditor. VaultBurn discovers decisions; it never makes them.",
+        epilog=HELP_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("csv", nargs="?", help="CSV file (see schema below)")
+    p.add_argument("--json", metavar="OUT", help="write JSON report")
+    p.add_argument("--init", metavar="CSV", nargs="?", const="subs.csv",
+                   help="generate CSV template")
+    p.add_argument("--stale-after", type=int, default=DEFAULT_STALE_AFTER,
+                   metavar="N",
+                   help=f"review threshold in days (default: {DEFAULT_STALE_AFTER}) "
+                        "— not an industry standard")
+    p.add_argument("--duplicate-threshold", type=Decimal,
+                   default=DEFAULT_DUP_THRESHOLD, metavar="USD",
+                   help=f"floor for duplicate groups (default: {DEFAULT_DUP_THRESHOLD})")
+    p.add_argument("--license", action="store_true")
+    p.add_argument("--version", action="version", version=VERSION)
+    a = p.parse_args()
+
+    if a.license:
+        print("MIT — VaultBurn v1.0.0. No server. No telemetry. No auto-decision.")
+        return
+    if a.init:
+        cmd_init(Path(a.init)); return
+    if not a.csv:
+        p.print_help(); return
+    if a.stale_after <= 0:
+        print("❌ --stale-after must be > 0", file=sys.stderr); sys.exit(2)
+    if a.duplicate_threshold < 0:
+        print("❌ --duplicate-threshold must be >= 0", file=sys.stderr); sys.exit(2)
+
+    rows = load(Path(a.csv))
+    rep = analyze(rows, a.stale_after, a.duplicate_threshold)
+    render(rep)
+    if a.json:
+        Path(a.json).write_text(
+            json.dumps(rep, ensure_ascii=False, indent=2, default=str),
+            encoding="utf-8")
+        print(f"✅ JSON: {a.json}")
+
+if __name__ == "__main__":
+    main()

vaultburn-1.0.0/vaultburn.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: vaultburn
+Version: 1.0.0
+Summary: Offline SaaS spend auditor. CSV in → decision report out. VaultBurn discovers decisions; it never makes them.
+Author-email: VaultBurn <vaultburn@proton.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/neverlose-io/vaultburn
+Project-URL: Repository, https://github.com/neverlose-io/vaultburn
+Project-URL: Issues, https://github.com/neverlose-io/vaultburn/issues
+Keywords: saas,audit,csv,offline,spend,decision-support
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# VaultBurn
+
+Offline SaaS spend auditor. CSV in → decision report out.
+
+**VaultBurn discovers decisions. It never makes them.**
+
+## Install
+
+```bash
+pip install vaultburn
+```
+
+Use
+
+```bash
+vaultburn subs.csv              # text report
+vaultburn subs.csv --json r.json
+vaultburn --init                # generate template
+vaultburn --help                # full schema & philosophy
+```
+
+Schema
+
+Required: name, monthly_cost, seats, used_seats, last_used
+
+Optional: renew_date, category, critical, reason, replacement_group, cost_model
+
+cost_model
+
+· per_seat (default): monthly_cost is the price per seat
+· flat: monthly_cost is the total monthly price
+
+Signals
+
+· monthly_spend — Sum of all subscriptions
+· unused_seat_cost — Idle seats × seat cost
+· potentially_cancellable — used=0 AND stale AND not critical
+· duplicate_candidate — From user-declared replacement groups
+· renewals_7d — Subscriptions renewing within 7 days
+
+Verdicts
+
+· cancellable — used=0, stale, not critical
+· review — needs human attention
+· protected — critical, never suggested for cancellation
+· ignored — user marked replacement_group=ignore
+· ok — clean
+
+What it does NOT do
+
+· No cloud. No OAuth. No accounts. No telemetry.
+· No auto-cancel. No auto-keep. No cheapest-wins.
+· No Stripe (yet — will add only if 3 users request it).
+
+Philosophy
+
+VaultBurn discovers decisions. It never makes them.
+
+License
+
+MIT.

vaultburn-1.0.0/vaultburn.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+vaultburn/__init__.py
+vaultburn.egg-info/PKG-INFO
+vaultburn.egg-info/SOURCES.txt
+vaultburn.egg-info/dependency_links.txt
+vaultburn.egg-info/entry_points.txt
+vaultburn.egg-info/top_level.txt

vaultburn-1.0.0/vaultburn.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vaultburn-1.0.0/vaultburn.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vaultburn = vaultburn:main

vaultburn-1.0.0/vaultburn.egg-info/top_level.txt

@@ -0,0 +1 @@
+vaultburn