rootecho 0.1.0__tar.gz

rootecho-0.1.0/LICENSE

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

rootecho-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: rootecho
+Version: 0.1.0
+Summary: Catch recurring root causes across postmortems. Zero dependencies, no server.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/rootecho-py
+Project-URL: Repository, https://github.com/jjdoor/rootecho-py
+Project-URL: Issues, https://github.com/jjdoor/rootecho-py/issues
+Keywords: postmortem,incident,sre,devops,root-cause,cli,incident-response,reliability,on-call
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# rootecho
+
+**Catch recurring root causes across postmortems.** Heavyweight incident
+platforms (rootly, incident.io) flag when a new incident shares a root cause
+with a past one — teams without that budget just... don't find out, until the
+same failure bites twice. `rootecho` does the comparison locally: no account,
+no server, your incident history lives in your repo.
+
+```bash
+pip install rootecho
+rootecho init incident.json      # scaffold a postmortem
+rootecho add incident.json       # record it, flag any echo of a past root cause
+rootecho check incident.json     # same check, no recording — use as a CI gate
+```
+
+This is the Python build — a Node build (`npx rootecho`) exists too and reads
+the exact same `.rootecho/history.jsonl`, so a team split across both
+ecosystems shares one history.
+
+## Why
+
+> "We use rootly to track this automatically. It flags when incidents have the
+> same root cause as previous ones."
+
+That's a paid, hosted feature. For everyone else, a postmortem gets written,
+action items get filed, and six months later the exact same root cause causes
+the exact same outage — because nobody had a system for "hey, we've seen this
+before, and last time's fix never shipped." `rootecho` is that system, as a
+zero-dependency local CLI.
+
+## How it works
+
+1. **Each postmortem is one JSON record** — `root_cause` (free text) and/or
+   `root_cause_tags` (curated labels), plus `action_items` with a status.
+2. **`add`/`check` compare it against your history** using Jaccard similarity
+   over tags (primary signal) blended with free-text overlap (secondary). No
+   ML dependency, no network call.
+3. **A match above the threshold prints the past incident's action items** —
+   so you see immediately whether last time's fix ever actually shipped.
+
+## Incident format
+
+```json
+{
+  "id": "INC-2026-014",
+  "date": "2026-07-03",
+  "title": "Payment webhook retries exhausted",
+  "root_cause": "webhook retry queue misconfigured to drop after 3 attempts, no dead-letter fallback",
+  "root_cause_tags": ["webhook", "retry-queue", "dead-letter", "config"],
+  "action_items": [
+    { "id": "AI-1", "description": "Add dead-letter queue for webhook retries", "owner": "alice", "status": "open", "due_date": "2026-07-20" }
+  ]
+}
+```
+
+Only `id` and one of `root_cause`/`root_cause_tags` are required. `rootecho init`
+writes a starter file.
+
+## Example
+
+```
+$ rootecho add inc-2026-014.json
+⚠ root cause echo detected for "INC-2026-014":
+
+  INC-2026-003 (2026-03-15) — 100% similar root cause
+  Payment webhook retries exhausted
+    ✓ Add retry backoff [done]
+    ✗ Add monitoring alert for queue depth [open] — 93d overdue
+  → 1 action item(s) from this past incident were never finished.
+
+recorded to .rootecho/history.jsonl
+```
+
+## Commands
+
+```bash
+rootecho add <file>      # record + compare (always exits 0 on success)
+rootecho check <file>    # compare only, no recording — exit 1 if an echo is found
+rootecho list [--json]   # show recorded incidents and open action-item counts
+rootecho init [file]     # write a starter incident.json
+```
+
+Flags: `--dir <path>` (state location), `--threshold <0-1>` (default `0.34`,
+lower = more sensitive), `--json`, `--force` (init: overwrite; add: allow a
+duplicate id).
+
+## Storage
+
+History is a JSON-Lines file at `.rootecho/history.jsonl`, **local to your
+project by default** (not your home directory) — the idea is your team commits
+it alongside the postmortems it describes, so `git blame`/`git log` on the file
+doubles as an incident timeline. Override the location with `--dir` or
+`$ROOTECHO_HOME`.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | `add` succeeded, or `check` found no echo |
+| `1` | `check` found an echo of a past root cause |
+| `2` | error (bad args, invalid JSON, duplicate id) |
+
+## License
+
+MIT

rootecho-0.1.0/README.md

@@ -0,0 +1,105 @@
+# rootecho
+
+**Catch recurring root causes across postmortems.** Heavyweight incident
+platforms (rootly, incident.io) flag when a new incident shares a root cause
+with a past one — teams without that budget just... don't find out, until the
+same failure bites twice. `rootecho` does the comparison locally: no account,
+no server, your incident history lives in your repo.
+
+```bash
+pip install rootecho
+rootecho init incident.json      # scaffold a postmortem
+rootecho add incident.json       # record it, flag any echo of a past root cause
+rootecho check incident.json     # same check, no recording — use as a CI gate
+```
+
+This is the Python build — a Node build (`npx rootecho`) exists too and reads
+the exact same `.rootecho/history.jsonl`, so a team split across both
+ecosystems shares one history.
+
+## Why
+
+> "We use rootly to track this automatically. It flags when incidents have the
+> same root cause as previous ones."
+
+That's a paid, hosted feature. For everyone else, a postmortem gets written,
+action items get filed, and six months later the exact same root cause causes
+the exact same outage — because nobody had a system for "hey, we've seen this
+before, and last time's fix never shipped." `rootecho` is that system, as a
+zero-dependency local CLI.
+
+## How it works
+
+1. **Each postmortem is one JSON record** — `root_cause` (free text) and/or
+   `root_cause_tags` (curated labels), plus `action_items` with a status.
+2. **`add`/`check` compare it against your history** using Jaccard similarity
+   over tags (primary signal) blended with free-text overlap (secondary). No
+   ML dependency, no network call.
+3. **A match above the threshold prints the past incident's action items** —
+   so you see immediately whether last time's fix ever actually shipped.
+
+## Incident format
+
+```json
+{
+  "id": "INC-2026-014",
+  "date": "2026-07-03",
+  "title": "Payment webhook retries exhausted",
+  "root_cause": "webhook retry queue misconfigured to drop after 3 attempts, no dead-letter fallback",
+  "root_cause_tags": ["webhook", "retry-queue", "dead-letter", "config"],
+  "action_items": [
+    { "id": "AI-1", "description": "Add dead-letter queue for webhook retries", "owner": "alice", "status": "open", "due_date": "2026-07-20" }
+  ]
+}
+```
+
+Only `id` and one of `root_cause`/`root_cause_tags` are required. `rootecho init`
+writes a starter file.
+
+## Example
+
+```
+$ rootecho add inc-2026-014.json
+⚠ root cause echo detected for "INC-2026-014":
+
+  INC-2026-003 (2026-03-15) — 100% similar root cause
+  Payment webhook retries exhausted
+    ✓ Add retry backoff [done]
+    ✗ Add monitoring alert for queue depth [open] — 93d overdue
+  → 1 action item(s) from this past incident were never finished.
+
+recorded to .rootecho/history.jsonl
+```
+
+## Commands
+
+```bash
+rootecho add <file>      # record + compare (always exits 0 on success)
+rootecho check <file>    # compare only, no recording — exit 1 if an echo is found
+rootecho list [--json]   # show recorded incidents and open action-item counts
+rootecho init [file]     # write a starter incident.json
+```
+
+Flags: `--dir <path>` (state location), `--threshold <0-1>` (default `0.34`,
+lower = more sensitive), `--json`, `--force` (init: overwrite; add: allow a
+duplicate id).
+
+## Storage
+
+History is a JSON-Lines file at `.rootecho/history.jsonl`, **local to your
+project by default** (not your home directory) — the idea is your team commits
+it alongside the postmortems it describes, so `git blame`/`git log` on the file
+doubles as an incident timeline. Override the location with `--dir` or
+`$ROOTECHO_HOME`.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | `add` succeeded, or `check` found no echo |
+| `1` | `check` found an echo of a past root cause |
+| `2` | error (bad args, invalid JSON, duplicate id) |
+
+## License
+
+MIT

rootecho-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rootecho"
+version = "0.1.0"
+description = "Catch recurring root causes across postmortems. Zero dependencies, no server."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "yyfjj" }]
+keywords = ["postmortem", "incident", "sre", "devops", "root-cause", "cli", "incident-response", "reliability", "on-call"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Monitoring",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/jjdoor/rootecho-py"
+Repository = "https://github.com/jjdoor/rootecho-py"
+Issues = "https://github.com/jjdoor/rootecho-py/issues"
+
+[project.scripts]
+rootecho = "rootecho.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

rootecho-0.1.0/setup.cfg

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

rootecho-0.1.0/src/rootecho/__init__.py

@@ -0,0 +1,3 @@
+"""rootecho — catch recurring root causes across postmortems. Zero dependencies."""
+
+__version__ = "0.1.0"

rootecho-0.1.0/src/rootecho/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

rootecho-0.1.0/src/rootecho/cli.py

@@ -0,0 +1,284 @@
+"""rootecho command-line interface."""
+
+import json
+import math
+import os
+import re
+import sys
+from datetime import datetime, timezone
+
+from . import core, store
+from .core import now_ms
+
+_NUM_RE = re.compile(r"^-?\d+(\.\d+)?$")
+_CTRL_RE = re.compile(r"[\x00-\x1f\x7f]")
+
+
+def sanitize(s):
+    """Strip C0 control characters (including ESC, the start of ANSI escape
+    sequences) and DEL from incident-supplied text before it hits the
+    terminal — an incident.json (or a shared history.jsonl entry someone
+    else wrote) is untrusted input, and its id/title/description fields are
+    printed verbatim."""
+    return _CTRL_RE.sub("", "" if s is None else str(s))
+
+
+def _json_number(x):
+    """Render a whole-number float as an int before JSON-encoding it, so
+    Python's json module doesn't emit a trailing ``.0`` where Node's
+    JSON.stringify wouldn't (e.g. an exact-match similarity score of 1.0 vs
+    1) — the two builds must produce byte-identical --json output."""
+    if isinstance(x, float) and x.is_integer():
+        return int(x)
+    return x
+
+
+def _round_half_up(x):
+    """Round-half-away-from-zero, matching JS's Math.round — Python's builtin
+    round() uses banker's rounding (round-half-to-even), which disagrees with
+    Math.round on exact .5 boundaries (round(12.5) == 12 in Python but
+    Math.round(12.5) === 13 in JS)."""
+    return math.floor(x + 0.5)
+
+VERSION = "0.1.0"
+
+# ---- tiny color helpers (no dep) ----
+_COLOR = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def _c(code, s):
+    return f"\x1b[{code}m{s}\x1b[0m" if _COLOR else s
+
+
+def red(s): return _c("31", s)
+def green(s): return _c("32", s)
+def yellow(s): return _c("33", s)
+def dim(s): return _c("2", s)
+def bold(s): return _c("1", s)
+
+
+HELP = f"""{bold('rootecho')} — catch recurring root causes across postmortems. Local, no server.
+
+{bold('Record & compare')}
+  rootecho add <incident.json>     Record a postmortem, flag if its root cause echoes a past one
+  rootecho check <incident.json>   Same comparison without recording (CI gate: exit 1 on echo)
+
+{bold('Inspect')}
+  rootecho list [--json]           Show recorded incidents and their open action items
+  rootecho init [file] [--force]   Write a starter incident.json template
+
+{bold('Options')}  --dir <path>  --threshold <0-1, default 0.34>  --json  --force  --version
+
+{bold('Exit')}  0 no echo / ok   1 echo detected (check only)   2 usage or input error
+"""
+
+
+def fail(msg):
+    sys.stderr.write(red(f"rootecho: {msg}\n"))
+    sys.exit(2)
+
+
+def flag(args, name):
+    """Value after --name, or None. Won't return a token that itself looks
+    like a flag (e.g. `--dir --force` must not treat "--force" as the
+    directory)."""
+    if name in args:
+        i = args.index(name)
+        if i + 1 < len(args):
+            v = args[i + 1]
+            if not v.startswith("--"):
+                return v
+    return None
+
+
+def has(args, name):
+    return name in args
+
+
+# ---- commands --------------------------------------------------------------
+
+def read_incident(file):
+    if not file or file.startswith("-"):
+        fail("needs an <incident.json> path")
+    try:
+        with open(file, "r", encoding="utf-8") as f:
+            raw = f.read()
+    except (OSError, UnicodeDecodeError) as e:
+        fail(f'cannot read "{file}": {e}')
+    try:
+        incident = json.loads(raw)
+    except (ValueError, RecursionError) as e:
+        fail(f'"{file}" is not valid JSON: {e}')
+    errors = core.validate_incident(incident)
+    if errors:
+        fail(f'"{file}" is missing required fields:\n  - ' + "\n  - ".join(errors))
+    if not incident.get("date"):
+        incident["date"] = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    return incident
+
+
+def print_matches(incident, matches, t):
+    if not matches:
+        sys.stdout.write(green(f"✓ no echo — \"{sanitize(incident['id'])}\" looks like a new root cause\n"))
+        return
+    sys.stdout.write(yellow(f"⚠ root cause echo detected for \"{sanitize(incident['id'])}\":\n"))
+    for m in matches:
+        past = m["incident"]
+        pct = _round_half_up(m["score"] * 100)
+        past_id = sanitize(past.get("id"))
+        past_date = sanitize(past.get("date"))
+        sys.stdout.write(f"\n  {bold(past_id)} ({past_date}) — {pct}% similar root cause\n")
+        if past.get("title"):
+            sys.stdout.write(f"  {dim(sanitize(past['title']))}\n")
+        items = core.summarize_action_items(past.get("action_items"), t)
+        if not items:
+            continue
+        for it in items:
+            mark = green("✓") if it["done"] else (red("✗") if it["overdue"] else yellow("○"))
+            label = sanitize(it.get("description") or it.get("id") or "(action item)")
+            suffix = ""
+            if not it["done"] and it["overdue"]:
+                suffix = red(f" — {it['overdueDays']}d overdue")
+            status_tag = dim("[" + sanitize(it["status"]) + "]")
+            sys.stdout.write(f"    {mark} {label} {status_tag}{suffix}\n")
+        unfinished = [it for it in items if not it["done"]]
+        if unfinished:
+            sys.stdout.write(dim(f"  → {len(unfinished)} action item(s) from this past incident were never finished.\n"))
+
+
+def cmd_add_or_check(mode, args):
+    file = args[0] if args else None
+    opts = args[1:]
+
+    threshold = 0.34
+    if has(opts, "--threshold"):
+        raw = flag(opts, "--threshold")
+        if raw is None or not _NUM_RE.match(raw):
+            fail("--threshold must be a number between 0 and 1")
+        threshold = float(raw)
+    if threshold < 0 or threshold > 1:
+        fail("--threshold must be a number between 0 and 1")
+    dir_ = flag(opts, "--dir")
+    as_json = has(opts, "--json")
+    t = now_ms()
+
+    incident = read_incident(file)
+    history = store.load_history(dir_)
+
+    if mode == "add" and any(h.get("id") == incident["id"] for h in history) and not has(opts, "--force"):
+        fail(f"incident \"{incident['id']}\" is already recorded (use a different id, or --force to append a duplicate)")
+
+    matches = core.find_matches(incident, history, threshold)
+
+    if as_json:
+        out = {
+            "id": incident["id"],
+            "echoDetected": len(matches) > 0,
+            "matches": [
+                {
+                    "id": m["incident"].get("id"),
+                    "date": m["incident"].get("date"),
+                    "score": _json_number(m["score"]),
+                    "actionItems": core.summarize_action_items(m["incident"].get("action_items"), t),
+                }
+                for m in matches
+            ],
+        }
+        sys.stdout.write(json.dumps(out, indent=2, ensure_ascii=False) + "\n")
+    else:
+        print_matches(incident, matches, t)
+
+    if mode == "add":
+        store.append_incident(incident, dir_)
+        if not as_json:
+            sys.stdout.write(dim(f"\nrecorded to {store.history_path(dir_)}\n"))
+        sys.exit(0)
+    sys.exit(1 if matches else 0)
+
+
+def cmd_list(args):
+    dir_ = flag(args, "--dir")
+    as_json = has(args, "--json")
+    history = store.load_history(dir_)
+    t = now_ms()
+
+    if as_json:
+        rows = []
+        for inc in history:
+            open_count = sum(1 for it in core.summarize_action_items(inc.get("action_items"), t) if not it["done"])
+            rows.append({
+                "id": inc.get("id"),
+                "date": inc.get("date"),
+                "title": inc.get("title"),
+                "tags": core.normalize_tags(inc.get("root_cause_tags")),
+                "openActionItems": open_count,
+            })
+        sys.stdout.write(json.dumps(rows, indent=2, ensure_ascii=False) + "\n")
+        return
+
+    if not history:
+        sys.stdout.write(dim("no incidents recorded yet. Track one with: rootecho add <incident.json>\n"))
+        return
+    for inc in history:
+        open_count = sum(1 for it in core.summarize_action_items(inc.get("action_items"), t) if not it["done"])
+        open_str = yellow(f"{open_count} open") if open_count > 0 else dim("0 open")
+        tags = ", ".join(core.normalize_tags(inc.get("root_cause_tags")))
+        inc_id = sanitize(inc.get("id"))
+        inc_date = sanitize(inc.get("date")) or "?"
+        sys.stdout.write(f"{bold(inc_id.ljust(20))} {dim(inc_date)}  {open_str.ljust(18)} {dim(tags)}\n")
+
+
+def _template():
+    return {
+        "id": "INC-YYYY-NNN",
+        "date": datetime.now(timezone.utc).strftime("%Y-%m-%d"),
+        "title": "Short incident title",
+        "service": "service-name",
+        "severity": "sev2",
+        "root_cause": "Describe what actually caused it, not just the symptom.",
+        "root_cause_tags": ["tag-one", "tag-two"],
+        "action_items": [
+            {"id": "AI-1", "description": "What will prevent this from recurring", "owner": "someone", "status": "open", "due_date": None},
+        ],
+    }
+
+
+def cmd_init(args):
+    file = args[0] if args and not args[0].startswith("--") else "incident.json"
+    if os.path.exists(file) and not has(args, "--force"):
+        fail(f'"{file}" already exists (use --force to overwrite)')
+    with open(file, "w", encoding="utf-8") as f:
+        f.write(json.dumps(_template(), indent=2, ensure_ascii=False) + "\n")
+    sys.stdout.write(green(f"✓ wrote template to {file}\n"))
+
+
+def main():
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help"):
+        sys.stdout.write(HELP)
+        return 0
+    if argv[0] in ("-v", "--version"):
+        sys.stdout.write(VERSION + "\n")
+        return 0
+
+    command, rest = argv[0], argv[1:]
+    try:
+        if command == "add":
+            cmd_add_or_check("add", rest)
+        elif command == "check":
+            cmd_add_or_check("check", rest)
+        elif command == "list":
+            cmd_list(rest)
+        elif command == "init":
+            cmd_init(rest)
+        else:
+            fail(f"unknown command: {command} (try --help)")
+    except SystemExit:
+        raise
+    except Exception as e:
+        fail(str(e))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rootecho-0.1.0/src/rootecho/core.py

@@ -0,0 +1,173 @@
+"""rootecho core — pure root-cause similarity + action-item health logic.
+
+No fs, no clock, no network. Timestamps are epoch **milliseconds** to match
+the Node implementation byte-for-byte (both read/write the same
+``.rootecho/history.jsonl``).
+"""
+
+import re
+import time
+
+DAY_MS = 86_400_000
+
+# Common English filler words stripped before free-text comparison so two
+# unrelated incidents that both happen to say "the service was down" don't
+# score a false match on stopwords alone.
+STOPWORDS = {
+    "a", "an", "the", "to", "of", "in", "on", "for", "and", "or", "is", "was",
+    "were", "be", "been", "with", "that", "this", "it", "as", "at", "by",
+    "from", "which", "when", "due", "because", "not", "no", "did", "does",
+    "do", "after", "before", "during", "then", "than", "into", "out",
+}
+
+_WORD_RE = re.compile(r"[^a-z0-9]+")
+
+
+def now_ms() -> int:
+    """Current epoch time in milliseconds (matches JS ``Date.now()``)."""
+    return int(time.time() * 1000)
+
+
+def tokenize(text) -> list:
+    """Lowercase, strip punctuation, split on whitespace, drop stopwords and
+    single-character tokens."""
+    if not text:
+        return []
+    words = _WORD_RE.sub(" ", str(text).lower()).strip().split()
+    return [w for w in words if len(w) > 1 and w not in STOPWORDS]
+
+
+def normalize_tags(tags) -> list:
+    """Lowercase + trim + dedupe a tag list (order preserved). Non-list input
+    becomes []; entries that aren't already str/int/float are dropped (not
+    stringified) so a stray ``None``/object in the list can't turn into a
+    bogus "none" token that two unrelated incidents could spuriously share.
+    Booleans are excluded even though ``bool`` is an ``int`` subclass, to
+    match the JS implementation (``typeof true !== 'number'``)."""
+    if not isinstance(tags, list):
+        return []
+    seen = set()
+    out = []
+    for t in tags:
+        if isinstance(t, bool) or not isinstance(t, (str, int, float)):
+            continue
+        v = str(t).strip().lower()
+        if v and v not in seen:
+            seen.add(v)
+            out.append(v)
+    return out
+
+
+def jaccard(a, b) -> float:
+    """Jaccard similarity between two token/tag lists: |intersection| / |union|.
+    Two empty sets score 0 (no signal, not a match)."""
+    set_a, set_b = set(a), set(b)
+    if not set_a and not set_b:
+        return 0.0
+    inter = len(set_a & set_b)
+    union = len(set_a) + len(set_b) - inter
+    return 0.0 if union == 0 else inter / union
+
+
+def similarity(a: dict, b: dict) -> float:
+    """Similarity score between two incidents' root causes, 0..1.
+
+    ``root_cause_tags`` is the primary signal (curated, low-noise) when both
+    incidents have tags — blended 70/30 with free-text overlap. If either
+    side lacks tags, falls back to free-text ``root_cause`` overlap alone.
+    """
+    tags_a = normalize_tags(a.get("root_cause_tags"))
+    tags_b = normalize_tags(b.get("root_cause_tags"))
+    text_score = jaccard(tokenize(a.get("root_cause")), tokenize(b.get("root_cause")))
+
+    if tags_a and tags_b:
+        tag_score = jaccard(tags_a, tags_b)
+        return tag_score * 0.7 + text_score * 0.3
+    return text_score
+
+
+def find_matches(incident: dict, history: list, threshold: float = 0.34) -> list:
+    """Find past incidents whose root cause echoes ``incident``'s, sorted by
+    score (desc), then by date (desc, most recent first). Excludes an
+    incident from matching itself by id.
+
+    Returns a list of ``{"incident": ..., "score": ...}`` dicts.
+    """
+    candidates = [
+        {"incident": past, "score": similarity(incident, past)}
+        for past in history
+        if past.get("id") != incident.get("id")
+    ]
+    matches = [m for m in candidates if m["score"] >= threshold]
+    matches.sort(key=lambda m: (m["score"], str(m["incident"].get("date", ""))), reverse=True)
+    return matches
+
+
+def action_item_health(item: dict, now: int) -> dict:
+    """Compute one action item's health at time ``now`` (ms)."""
+    status = item.get("status") or "open"
+    done = status in ("done", "cancelled")
+    overdue_days = 0
+    due_date = item.get("due_date")
+    if not done and due_date:
+        due = _parse_date_ms(due_date)
+        if due is not None and now > due:
+            overdue_days = (now - due) // DAY_MS
+    return {**item, "status": status, "done": done, "overdue": overdue_days > 0, "overdueDays": overdue_days}
+
+
+def summarize_action_items(items, now: int) -> list:
+    """Map ``action_item_health`` over a list, tolerating a missing/non-list
+    input. Non-dict entries (e.g. a stray ``None`` or string from a
+    hand-edited file) are dropped rather than crashing — same "one bad entry
+    doesn't take down the rest" tolerance as history-file loading."""
+    if not isinstance(items, list):
+        return []
+    return [action_item_health(it, now) for it in items if isinstance(it, dict)]
+
+
+def validate_incident(incident) -> list:
+    """Validate the minimal shape rootecho needs from an incident record.
+    Returns human-readable problems; empty list = valid."""
+    if not isinstance(incident, dict):
+        return ["incident must be a JSON object"]
+    errors = []
+    if not incident.get("id") or not isinstance(incident.get("id"), str):
+        errors.append('missing "id" (string)')
+    tags = incident.get("root_cause_tags")
+    has_tags = isinstance(tags, list) and len(tags) > 0
+    text = incident.get("root_cause")
+    has_text = isinstance(text, str) and text.strip() != ""
+    if not has_tags and not has_text:
+        errors.append('missing both "root_cause" and "root_cause_tags" — need at least one')
+    return errors
+
+
+# Strict ISO 8601 date/datetime, UTC only (no numeric offsets — unsupported
+# for now, see README). Matches YYYY-MM-DD or YYYY-MM-DD[T ]HH:MM:SS[.sss][Z].
+# Deliberately narrower than (and independent of) datetime.fromisoformat,
+# whose accepted grammar varies across Python 3.8-3.11+ and diverges from JS
+# Date.parse — both implementations must agree on exactly which due_date
+# strings are valid, or one silently computes "not overdue" for a date the
+# other correctly flags.
+_ISO_DATE_RE = re.compile(
+    r"^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?Z?)?$"
+)
+
+
+def _parse_date_ms(value):
+    """Parse a strict ISO 8601 UTC date/datetime string to epoch ms, or None
+    if ``value`` isn't a string in the accepted shape or isn't a real
+    calendar date."""
+    if not isinstance(value, str):
+        return None
+    m = _ISO_DATE_RE.match(value.strip())
+    if not m:
+        return None
+    y, mo, d, h, mi, s = m.groups()
+    from datetime import datetime, timezone
+    try:
+        dt = datetime(int(y), int(mo), int(d), int(h or 0), int(mi or 0), int(s or 0), tzinfo=timezone.utc)
+    except ValueError:
+        return None  # e.g. month=13, day=32, Feb 30 — not a real calendar date
+    return int(dt.timestamp() * 1000)

rootecho-0.1.0/src/rootecho/store.py

@@ -0,0 +1,56 @@
+"""rootecho persistence.
+
+History is a JSON-Lines file (one incident object per line) under a
+project-local directory, default ``.rootecho/`` in the current working
+directory — meant to be committed to the team's repo so the whole team
+shares (and diffs) incident history, unlike a per-machine dotfile. Override
+with ``$ROOTECHO_HOME`` for tests or a non-default layout. The on-disk format
+is identical to the Node implementation.
+"""
+
+import json
+import os
+from pathlib import Path
+
+
+def default_dir() -> Path:
+    return Path(os.environ.get("ROOTECHO_HOME") or (Path.cwd() / ".rootecho"))
+
+
+def history_path(dir_=None) -> Path:
+    return Path(dir_ or default_dir()) / "history.jsonl"
+
+
+def load_history(dir_=None) -> list:
+    """Load all incidents from the history file. Corrupt/blank lines —
+    including lines that are syntactically valid JSON but not an object
+    (``null``, a bare number, a string, an array) — are skipped rather than
+    failing the whole load — one bad line (e.g. a botched manual edit or
+    merge) shouldn't lose the rest of the team's history."""
+    p = history_path(dir_)
+    if not p.exists():
+        return []
+    out = []
+    for line in p.read_text(encoding="utf-8").split("\n"):
+        t = line.strip()
+        if not t:
+            continue
+        try:
+            parsed = json.loads(t)
+        except ValueError:
+            continue  # skip corrupt line
+        if isinstance(parsed, dict):
+            out.append(parsed)
+    return out
+
+
+def append_incident(incident: dict, dir_=None) -> None:
+    """Append one incident record as a new line. Creates the directory/file
+    if needed. ``ensure_ascii=False`` so non-ASCII text (e.g. Chinese in a
+    title) is written as raw UTF-8 — matching Node's ``JSON.stringify``,
+    which never escapes it — so the shared history.jsonl is byte-identical
+    regardless of which build wrote a given line."""
+    d = Path(dir_ or default_dir())
+    d.mkdir(parents=True, exist_ok=True)
+    with open(history_path(d), "a", encoding="utf-8") as f:
+        f.write(json.dumps(incident, ensure_ascii=False) + "\n")

rootecho-0.1.0/src/rootecho.egg-info/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: rootecho
+Version: 0.1.0
+Summary: Catch recurring root causes across postmortems. Zero dependencies, no server.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/rootecho-py
+Project-URL: Repository, https://github.com/jjdoor/rootecho-py
+Project-URL: Issues, https://github.com/jjdoor/rootecho-py/issues
+Keywords: postmortem,incident,sre,devops,root-cause,cli,incident-response,reliability,on-call
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# rootecho
+
+**Catch recurring root causes across postmortems.** Heavyweight incident
+platforms (rootly, incident.io) flag when a new incident shares a root cause
+with a past one — teams without that budget just... don't find out, until the
+same failure bites twice. `rootecho` does the comparison locally: no account,
+no server, your incident history lives in your repo.
+
+```bash
+pip install rootecho
+rootecho init incident.json      # scaffold a postmortem
+rootecho add incident.json       # record it, flag any echo of a past root cause
+rootecho check incident.json     # same check, no recording — use as a CI gate
+```
+
+This is the Python build — a Node build (`npx rootecho`) exists too and reads
+the exact same `.rootecho/history.jsonl`, so a team split across both
+ecosystems shares one history.
+
+## Why
+
+> "We use rootly to track this automatically. It flags when incidents have the
+> same root cause as previous ones."
+
+That's a paid, hosted feature. For everyone else, a postmortem gets written,
+action items get filed, and six months later the exact same root cause causes
+the exact same outage — because nobody had a system for "hey, we've seen this
+before, and last time's fix never shipped." `rootecho` is that system, as a
+zero-dependency local CLI.
+
+## How it works
+
+1. **Each postmortem is one JSON record** — `root_cause` (free text) and/or
+   `root_cause_tags` (curated labels), plus `action_items` with a status.
+2. **`add`/`check` compare it against your history** using Jaccard similarity
+   over tags (primary signal) blended with free-text overlap (secondary). No
+   ML dependency, no network call.
+3. **A match above the threshold prints the past incident's action items** —
+   so you see immediately whether last time's fix ever actually shipped.
+
+## Incident format
+
+```json
+{
+  "id": "INC-2026-014",
+  "date": "2026-07-03",
+  "title": "Payment webhook retries exhausted",
+  "root_cause": "webhook retry queue misconfigured to drop after 3 attempts, no dead-letter fallback",
+  "root_cause_tags": ["webhook", "retry-queue", "dead-letter", "config"],
+  "action_items": [
+    { "id": "AI-1", "description": "Add dead-letter queue for webhook retries", "owner": "alice", "status": "open", "due_date": "2026-07-20" }
+  ]
+}
+```
+
+Only `id` and one of `root_cause`/`root_cause_tags` are required. `rootecho init`
+writes a starter file.
+
+## Example
+
+```
+$ rootecho add inc-2026-014.json
+⚠ root cause echo detected for "INC-2026-014":
+
+  INC-2026-003 (2026-03-15) — 100% similar root cause
+  Payment webhook retries exhausted
+    ✓ Add retry backoff [done]
+    ✗ Add monitoring alert for queue depth [open] — 93d overdue
+  → 1 action item(s) from this past incident were never finished.
+
+recorded to .rootecho/history.jsonl
+```
+
+## Commands
+
+```bash
+rootecho add <file>      # record + compare (always exits 0 on success)
+rootecho check <file>    # compare only, no recording — exit 1 if an echo is found
+rootecho list [--json]   # show recorded incidents and open action-item counts
+rootecho init [file]     # write a starter incident.json
+```
+
+Flags: `--dir <path>` (state location), `--threshold <0-1>` (default `0.34`,
+lower = more sensitive), `--json`, `--force` (init: overwrite; add: allow a
+duplicate id).
+
+## Storage
+
+History is a JSON-Lines file at `.rootecho/history.jsonl`, **local to your
+project by default** (not your home directory) — the idea is your team commits
+it alongside the postmortems it describes, so `git blame`/`git log` on the file
+doubles as an incident timeline. Override the location with `--dir` or
+`$ROOTECHO_HOME`.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | `add` succeeded, or `check` found no echo |
+| `1` | `check` found an echo of a past root cause |
+| `2` | error (bad args, invalid JSON, duplicate id) |
+
+## License
+
+MIT

rootecho-0.1.0/src/rootecho.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/rootecho/__init__.py
+src/rootecho/__main__.py
+src/rootecho/cli.py
+src/rootecho/core.py
+src/rootecho/store.py
+src/rootecho.egg-info/PKG-INFO
+src/rootecho.egg-info/SOURCES.txt
+src/rootecho.egg-info/dependency_links.txt
+src/rootecho.egg-info/entry_points.txt
+src/rootecho.egg-info/top_level.txt
+tests/test_core.py
+tests/test_store.py

rootecho-0.1.0/src/rootecho.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rootecho-0.1.0/src/rootecho.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rootecho = rootecho.cli:main

rootecho-0.1.0/src/rootecho.egg-info/top_level.txt

@@ -0,0 +1 @@
+rootecho

rootecho-0.1.0/tests/test_core.py

@@ -0,0 +1,160 @@
+from rootecho import core
+
+
+def test_tokenize_lowercases_strips_punctuation_drops_stopwords_and_single_chars():
+    assert core.tokenize("Webhook retry queue misconfigured to drop after 3 attempts!") == [
+        "webhook", "retry", "queue", "misconfigured", "drop", "attempts",
+    ]
+
+
+def test_tokenize_handles_empty_input():
+    assert core.tokenize("") == []
+    assert core.tokenize(None) == []
+
+
+def test_normalize_tags_lowercases_trims_dedupes_nonlist_becomes_empty():
+    assert core.normalize_tags([" Webhook ", "webhook", "Retry-Queue"]) == ["webhook", "retry-queue"]
+    assert core.normalize_tags(None) == []
+    assert core.normalize_tags("not-a-list") == []
+
+
+def test_normalize_tags_drops_none_dict_list_bool_entries_instead_of_stringifying():
+    # A stray None must NOT become the literal string "none" — two incidents
+    # that each merely contain a bad tag entry shouldn't spuriously match on it.
+    assert core.normalize_tags(["webhook", None, {}, ["nested"], True]) == ["webhook"]
+    assert core.normalize_tags([42, "webhook"]) == ["42", "webhook"]
+
+
+def test_jaccard_identical_disjoint_both_empty():
+    assert core.jaccard(["a", "b"], ["a", "b"]) == 1
+    assert core.jaccard(["a", "b"], ["c", "d"]) == 0
+    assert core.jaccard([], []) == 0
+
+
+def test_jaccard_partial_overlap():
+    assert core.jaccard(["a", "b", "c"], ["b", "c", "d"]) == 0.5
+
+
+def test_similarity_identical_tags_and_text_scores_one():
+    a = {"root_cause_tags": ["webhook", "retry-queue"], "root_cause": "queue misconfigured"}
+    b = {"root_cause_tags": ["webhook", "retry-queue"], "root_cause": "queue misconfigured"}
+    assert core.similarity(a, b) == 1
+
+
+def test_similarity_identical_tags_alone_not_certainty():
+    a = {"root_cause_tags": ["webhook", "retry-queue"], "root_cause": "x"}
+    b = {"root_cause_tags": ["webhook", "retry-queue"], "root_cause": "y"}
+    assert core.similarity(a, b) == 0.7
+
+
+def test_similarity_blends_tags_and_text():
+    a = {"root_cause_tags": ["webhook", "retry"], "root_cause": "queue misconfigured"}
+    b = {"root_cause_tags": ["webhook", "retry"], "root_cause": "totally different text here"}
+    assert core.similarity(a, b) == 0.7
+
+
+def test_similarity_falls_back_to_text_when_tags_missing():
+    a = {"root_cause": "database connection pool exhausted"}
+    b = {"root_cause_tags": [], "root_cause": "database connection pool exhausted"}
+    assert core.similarity(a, b) == 1
+
+
+def test_similarity_unrelated_incidents_score_low():
+    a = {"root_cause_tags": ["webhook", "retry-queue"], "root_cause": "webhook retry queue misconfigured"}
+    b = {"root_cause_tags": ["dns", "ttl"], "root_cause": "dns ttl cache expired unexpectedly"}
+    assert core.similarity(a, b) < 0.1
+
+
+def test_find_matches_filters_by_threshold_and_excludes_self_by_id():
+    incident = {"id": "INC-3", "root_cause_tags": ["webhook", "retry-queue"]}
+    history = [
+        {"id": "INC-1", "date": "2026-01-01", "root_cause_tags": ["webhook", "retry-queue"]},
+        {"id": "INC-2", "date": "2026-02-01", "root_cause_tags": ["dns", "ttl"]},
+        {"id": "INC-3", "date": "2026-03-01", "root_cause_tags": ["webhook", "retry-queue"]},
+    ]
+    matches = core.find_matches(incident, history, 0.34)
+    assert [m["incident"]["id"] for m in matches] == ["INC-1"]
+
+
+def test_find_matches_sorts_by_score_desc_then_date_desc():
+    incident = {"id": "NEW", "root_cause_tags": ["webhook", "retry-queue", "timeout"]}
+    history = [
+        {"id": "OLD-1", "date": "2026-01-01", "root_cause_tags": ["webhook", "retry-queue"]},
+        {"id": "OLD-2", "date": "2026-05-01", "root_cause_tags": ["webhook", "retry-queue", "timeout"]},
+        {"id": "OLD-3", "date": "2026-06-01", "root_cause_tags": ["webhook", "retry-queue"]},
+    ]
+    matches = core.find_matches(incident, history, 0.1)
+    assert [m["incident"]["id"] for m in matches] == ["OLD-2", "OLD-3", "OLD-1"]
+
+
+def test_find_matches_empty_history():
+    assert core.find_matches({"id": "X", "root_cause_tags": ["a"]}, [], 0.34) == []
+
+
+def test_action_item_health_done_cancelled_never_overdue():
+    t = core._parse_date_ms("2026-07-03")
+    assert core.action_item_health({"status": "done", "due_date": "2026-01-01"}, t)["overdue"] is False
+    assert core.action_item_health({"status": "cancelled", "due_date": "2026-01-01"}, t)["overdue"] is False
+
+
+def test_action_item_health_open_past_due_is_overdue_with_day_count():
+    t = core._parse_date_ms("2026-07-03T00:00:00Z")
+    item = {"status": "open", "due_date": "2026-06-28T00:00:00Z"}
+    r = core.action_item_health(item, t)
+    assert r["overdue"] is True
+    assert r["overdueDays"] == 5
+
+
+def test_action_item_health_open_without_due_date_never_overdue():
+    t = core._parse_date_ms("2026-07-03")
+    assert core.action_item_health({"status": "open"}, t)["overdue"] is False
+
+
+def test_action_item_health_missing_status_defaults_to_open():
+    t = core._parse_date_ms("2026-07-03")
+    assert core.action_item_health({}, t)["status"] == "open"
+
+
+def test_summarize_action_items_tolerates_missing_input():
+    t = core.now_ms()
+    assert core.summarize_action_items(None, t) == []
+    assert core.summarize_action_items("not-a-list", t) == []
+
+
+def test_summarize_action_items_drops_non_dict_entries_instead_of_crashing():
+    t = core.now_ms()
+    result = core.summarize_action_items([{"id": "AI-1", "status": "open"}, None, "oops", ["nested"], 42], t)
+    assert [r["id"] for r in result] == ["AI-1"]
+
+
+def test_parse_date_ms_accepts_strict_iso_rejects_garbage_and_offsets():
+    from datetime import datetime, timezone
+    expected = int(datetime(2026, 6, 28, tzinfo=timezone.utc).timestamp() * 1000)
+    assert core._parse_date_ms("2026-06-28") == expected
+    expected_dt = int(datetime(2026, 6, 28, 10, 30, 0, tzinfo=timezone.utc).timestamp() * 1000)
+    assert core._parse_date_ms("2026-06-28T10:30:00Z") == expected_dt
+    assert core._parse_date_ms("2026-06-28T10:30:00") == expected_dt
+    assert core._parse_date_ms("2026-6-28") is None  # not zero-padded
+    assert core._parse_date_ms("20260628") is None  # no dashes
+    assert core._parse_date_ms("2026-06-28T10:30:00+05:30") is None  # numeric offsets unsupported
+    assert core._parse_date_ms("2026-02-30") is None  # not a real calendar date
+    assert core._parse_date_ms("not a date") is None
+    assert core._parse_date_ms(None) is None
+    assert core._parse_date_ms(1234567890) is None
+
+
+def test_validate_incident_requires_id_and_root_cause_or_tags():
+    assert core.validate_incident({}) == [
+        'missing "id" (string)',
+        'missing both "root_cause" and "root_cause_tags" — need at least one',
+    ]
+    assert core.validate_incident({"id": "X", "root_cause": "y"}) == []
+    assert core.validate_incident({"id": "X", "root_cause_tags": ["a"]}) == []
+    assert core.validate_incident({"id": "X", "root_cause_tags": []}) == [
+        'missing both "root_cause" and "root_cause_tags" — need at least one',
+    ]
+
+
+def test_validate_incident_rejects_non_object():
+    assert core.validate_incident(None) == ["incident must be a JSON object"]
+    assert core.validate_incident([1, 2]) == ["incident must be a JSON object"]

rootecho-0.1.0/tests/test_store.py

@@ -0,0 +1,44 @@
+import os
+
+from rootecho import store
+
+
+def test_load_history_missing_file_returns_empty(tmp_path):
+    assert store.load_history(str(tmp_path)) == []
+
+
+def test_append_and_load_round_trip_preserves_order(tmp_path):
+    store.append_incident({"id": "A"}, str(tmp_path))
+    store.append_incident({"id": "B"}, str(tmp_path))
+    assert [i["id"] for i in store.load_history(str(tmp_path))] == ["A", "B"]
+
+
+def test_load_history_skips_corrupt_blank_lines(tmp_path):
+    p = store.history_path(str(tmp_path))
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text('{"id":"A"}\n\nnot json\n{"id":"B"}\n', encoding="utf-8")
+    assert [i["id"] for i in store.load_history(str(tmp_path))] == ["A", "B"]
+
+
+def test_load_history_skips_lines_that_are_valid_json_but_not_an_object(tmp_path):
+    p = store.history_path(str(tmp_path))
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text('{"id":"A"}\nnull\n42\n"oops"\n[1,2,3]\n{"id":"B"}\n', encoding="utf-8")
+    assert [i["id"] for i in store.load_history(str(tmp_path))] == ["A", "B"]
+
+
+def test_append_incident_writes_raw_utf8_not_escaped(tmp_path):
+    store.append_incident({"id": "A", "title": "数据库连接超时 🔥"}, str(tmp_path))
+    raw = store.history_path(str(tmp_path)).read_text(encoding="utf-8")
+    assert "数据库连接超时 🔥" in raw
+    assert "\\u" not in raw
+
+
+def test_default_dir_honors_env_override(monkeypatch):
+    monkeypatch.setenv("ROOTECHO_HOME", "/tmp/custom-rootecho")
+    assert str(store.default_dir()) == "/tmp/custom-rootecho"
+
+
+def test_default_dir_falls_back_to_cwd(monkeypatch):
+    monkeypatch.delenv("ROOTECHO_HOME", raising=False)
+    assert str(store.default_dir()) == str((os.getcwd() + "/.rootecho"))