Skip to content

gerodp/hermes-productivity-skills / reports/weekly-report

weekly-report

Verified

One weekly report combining Super Productivity time per project/task (with week-over-week deltas), Obsidian notes of the week grouped by folder (with key bullet points), emails sent this week, calendar events, git commits per repo, Claude Code sessions per project, and Umami page visits vs last week — with a skimmable TL;DR summary at the top.

scripts/render_markdown.py

View on GitHub
#!/usr/bin/env python3
"""render_markdown — turn a weekly-report JSON bundle into a faithful Markdown report.

Consumes the JSON bundle produced by ``weekly_report.py gather`` (the documented
contract — see the weekly-report SKILL.md) and renders a **deterministic** Markdown
report with **no LLM** in the loop. This is the reliable path for the data-dense
sections (emails, visits, commits, sessions, projects): every value is copied
straight from the bundle, so site names, recipients and counts are exact — a small
local model can't hallucinate a site name or drop an email row here.

The one thing an LLM would add over this renderer is prose bullet-point summaries of
each note body; those are optional. This renderer prints each note's body verbatim
(compacted), so the report is complete on its own.

Usage:
    weekly_report.py gather --period this-week | render_markdown.py > report.md
    render_markdown.py bundle.json --output report.md --title "Week 26"

Python standard library only.
"""
from __future__ import annotations

import argparse
import json
import sys


# --------------------------------------------------------------------------- #
# Helpers
# --------------------------------------------------------------------------- #
def md_cell(v):
    """A value safe to drop into a Markdown table cell (escape pipes and link
    brackets, flatten newlines). Brackets matter: an email subject like
    ``[pay now](https://evil)`` must not render as a live link. None → ''."""
    s = "" if v is None else str(v)
    s = s.replace("\\", "\\\\").replace("|", "\\|").replace("\n", " ")
    return s.replace("[", "\\[").replace("]", "\\]").strip()


def fmt_hours(h):
    try:
        return f"{float(h):.1f}h"
    except (TypeError, ValueError):
        return "0.0h"


def fmt_usd(x):
    try:
        v = float(x or 0)
    except (TypeError, ValueError):
        return "$0"
    return f"${v:.2f}" if v < 100 else f"${v:,.0f}"


def section_error(data):
    if isinstance(data, dict) and "error" in data:
        return data["error"]
    return None


def _pct_delta(cur, prev):
    """Compact ▲/▼ percentage delta of `cur` vs `prev`."""
    try:
        cur, prev = float(cur or 0), float(prev or 0)
    except (TypeError, ValueError):
        return ""
    if prev == 0:
        return "▲new" if cur else "—"
    pct = 100.0 * (cur - prev) / prev
    arrow = "▲" if pct > 0 else "▼" if pct < 0 else "—"
    return f"{arrow}{abs(pct):.0f}%"


def _fmt_secs(secs):
    try:
        secs = int(round(float(secs or 0)))
    except (TypeError, ValueError):
        return "—"
    m, s = divmod(secs, 60)
    return f"{m}m {s:02d}s" if m else f"{s}s"


def _table(headers, rows):
    """A GitHub-flavoured Markdown table (cells already md_cell-escaped)."""
    head = "| " + " | ".join(headers) + " |"
    sep = "| " + " | ".join("---" for _ in headers) + " |"
    body = ["| " + " | ".join(r) + " |" for r in rows]
    return "\n".join([head, sep] + body)


def _unavailable(err):
    return f"_unavailable: {err}_"


# --------------------------------------------------------------------------- #
# Sections
# --------------------------------------------------------------------------- #
def render_projects(data):
    out = ["## Projects & time"]
    err = section_error(data)
    if err:
        out.append(_unavailable(err))
        return "\n".join(out)
    projects = (data or {}).get("projects", []) or []
    if not projects:
        out.append("_No time tracked this week._")
        return "\n".join(out)
    has_prev = any("hours_prev" in p for p in projects)
    headers = ["Project", "Hours"] + (["Δ vs prev"] if has_prev else [])
    rows, total = [], 0.0
    for p in projects:
        hours = float(p.get("hours", 0) or 0)
        total += hours
        row = [md_cell(p.get("project", "?")), f"{hours:.2f}h"]
        if has_prev:
            row.append(_pct_delta(hours, p.get("hours_prev", 0)))
        rows.append(row)
    total_row = ["**Total**", f"**{total:.2f}h**"]
    if has_prev:
        total_row.append("**" + _pct_delta(
            total, sum(float(p.get("hours_prev", 0) or 0) for p in projects)) + "**")
    rows.append(total_row)
    out.append(_table(headers, rows))
    return "\n".join(out)


def render_calendar(data):
    out = ["## Calendar"]
    err = section_error(data)
    if err:
        out.append(_unavailable(err))
        return "\n".join(out)
    events = (data or {}).get("events", []) or []
    if not events:
        out.append("_No events this week._")
        return "\n".join(out)
    rows = []
    for ev in events:
        when = "all-day" if ev.get("all_day") else (
            f"{ev.get('start_local', '')}–{ev.get('end_local', '')}"
            if ev.get("end_local") else ev.get("start_local", ""))
        rows.append([md_cell(ev.get("day", "")), md_cell(when),
                     md_cell(ev.get("summary", "(no title)")),
                     md_cell(ev.get("location", ""))])
    out.append(_table(["Day", "When", "Event", "Location"], rows))
    if (data or {}).get("excluded"):
        out.append(f"\n_{data['excluded']} personal event(s) excluded._")
    return "\n".join(out)


def render_git(data):
    out = ["## Git activity"]
    err = section_error(data)
    if err:
        out.append(_unavailable(err))
        return "\n".join(out)
    repos = (data or {}).get("repos", []) or []
    total = (data or {}).get("total", sum(r.get("count", 0) for r in repos))
    if not repos:
        out.append("_No commits this week._")
        return "\n".join(out)
    for r in repos:
        churn = ""
        if "insertions" in r or "deletions" in r:
            churn = f" · +{r.get('insertions', 0)}/-{r.get('deletions', 0)}"
        out.append(f"\n**{md_cell(r.get('repo', '?'))}** "
                   f"({r.get('count', 0)} commit(s){churn})")
        for c in r.get("commits", []):
            out.append(f"- `{md_cell(c.get('short', ''))}` {md_cell(c.get('date', ''))} "
                       f"— {md_cell(c.get('subject', ''))}")
    out.append(f"\n**Total: {total} commit(s).**")
    return "\n".join(out)


def render_sessions(data):
    out = ["## Claude Code sessions"]
    err = section_error(data)
    if err:
        out.append(_unavailable(err))
        return "\n".join(out)
    projects = (data or {}).get("projects", []) or []
    if not projects:
        out.append("_No Claude Code sessions this week._")
        return "\n".join(out)
    total = (data or {}).get("total_sessions", sum(p.get("sessions", 0) for p in projects))
    total_cost = (data or {}).get("total_cost_usd", 0)
    for p in projects:
        out.append(f"\n**{md_cell(p.get('project', '?'))}** "
                   f"({p.get('sessions', 0)} session(s) · {fmt_usd(p.get('cost_usd', 0))} API-eq)")
        for e in p.get("entries", []):
            grade = f"[{e['grade']}] " if e.get("grade") else ""
            out.append(f"- {md_cell(e.get('when', ''))} · {md_cell(e.get('duration', ''))} · "
                       f"{grade}{md_cell(e.get('title', '(untitled)'))} · "
                       f"{fmt_usd(e.get('cost_usd', 0))}")
    out.append(f"\n**Total: {total} session(s) · {fmt_usd(total_cost)} "
               f"API-equivalent (list price — not your subscription bill).**")
    return "\n".join(out)


def render_notes(data):
    out = ["## Notes this week"]
    err = section_error(data)
    if err:
        out.append(_unavailable(err))
        return "\n".join(out)
    notes = (data or {}).get("notes", []) or []
    if not notes:
        out.append("_No notes modified this week._")
        return "\n".join(out)
    # Cluster by top-level folder (group).
    ordered = sorted(notes, key=lambda n: ((n.get("group") or "(root)") == "(root)",
                                           (n.get("group") or "(root)").lower()))
    cur_group = None
    for n in ordered:
        g = n.get("group") or "(root)"
        if g != cur_group:
            cur_group = g
            out.append(f"\n### {md_cell(g)}")
        title = n.get("name") or n.get("rel") or "(note)"
        out.append(f"\n**{md_cell(title)}** — mod {md_cell(n.get('modified', '?'))}")
        body = (n.get("body") or "").strip()
        if body:
            for ln in body.splitlines():
                out.append(f"> {ln}" if ln.strip() else ">")
            if n.get("truncated"):
                out.append("\n_(body truncated — raise --note-chars for more)_")
        else:
            out.append("_(empty note)_")
    if (data or {}).get("dropped"):
        out.append(f"\n_+{data['dropped']} more note(s) not shown._")
    if (data or {}).get("excluded"):
        out.append(f"\n_{data['excluded']} note(s) excluded by OBSIDIAN_EXCLUDE._")
    return "\n".join(out)


def render_emails(data):
    out = ["## Emails sent"]
    err = section_error(data)
    if err:
        out.append(_unavailable(err))
        return "\n".join(out)
    emails = (data or {}).get("emails", []) or []
    if not emails:
        out.append("_No emails sent this week._")
        return "\n".join(out)
    rows = []
    for e in emails:
        to = ", ".join(e.get("to") or []) or "(no recipient)"
        rows.append([md_cell(e.get("date", "")), md_cell(to),
                     md_cell(e.get("subject", "(no subject)"))])
    out.append(_table(["Date", "To", "Subject"], rows))
    out.append(f"\n**{len(emails)} email(s) sent this week.**")
    if (data or {}).get("possibly_truncated"):
        out.append("\n_(list may be incomplete — raise --max-emails.)_")
    return "\n".join(out)


def render_visits(data):
    out = ["## Visits vs last week"]
    err = section_error(data)
    if err:
        out.append(_unavailable(err))
        return "\n".join(out)
    sites = (data or {}).get("sites", []) or []
    if not sites:
        out.append("_No visit data available._")
        return "\n".join(out)
    has_id = any(s.get("site_id") for s in sites)
    headers = (["Site"] + (["Umami id"] if has_id else [])
               + ["Visitors", "Δ", "Visits", "Pageviews", "Bounce%", "Avg visit"])
    rows, tv, tvi, tp = [], 0, 0, 0
    for s in sites:
        v = s.get("visitors", 0) or 0
        vi = s.get("visits", 0) or 0
        pv = s.get("pageviews", 0) or 0
        tv += v
        tvi += vi
        tp += pv
        bounce = s.get("bounce_pct")
        row = [md_cell(s.get("name", "?"))]
        if has_id:
            row.append(md_cell(s.get("site_id", "")))
        row += [f"{v:,}", _pct_delta(v, s.get("visitors_prev", 0)), f"{vi:,}",
                f"{pv:,}", "—" if bounce is None else f"{float(bounce):.1f}%",
                _fmt_secs(s.get("avg_duration")) if s.get("avg_duration") is not None else "—"]
        rows.append(row)
    total_row = ["**Total**"] + (["**—**"] if has_id else []) + [
        f"**{tv:,}**", f"**{_pct_delta(tv, sum(s.get('visitors_prev', 0) or 0 for s in sites))}**",
        f"**{tvi:,}**", f"**{tp:,}**", "", ""]
    rows.append(total_row)
    out.append(_table(headers, rows))
    return "\n".join(out)


# --------------------------------------------------------------------------- #
# Assembly
# --------------------------------------------------------------------------- #
def build_markdown(bundle, *, title=None):
    rng = (bundle or {}).get("range", {}) or {}
    start, end = rng.get("start", "?"), rng.get("end", "?")
    label = rng.get("label")
    heading = title or "Weekly report"
    parts = [f"# {heading}",
             f"`{start} → {end}`" + (f" · {label}" if label else "")]
    summary = (bundle.get("summary") or {}).get("line")
    if summary:
        parts.append(f"\n**TL;DR:** {summary}")

    parts.append("\n" + render_projects(bundle.get("projects", {})))
    parts.append("\n" + render_calendar(bundle.get("calendar", {})))
    if bundle.get("git", bundle.get("commits")) is not None:
        parts.append("\n" + render_git(bundle.get("git", bundle.get("commits"))))
    if bundle.get("sessions") is not None:
        parts.append("\n" + render_sessions(bundle.get("sessions", {})))
    parts.append("\n" + render_notes(bundle.get("notes", {})))
    parts.append("\n" + render_emails(bundle.get("emails", {})))
    parts.append("\n" + render_visits(bundle.get("visits", {})))

    errors = bundle.get("errors") or []
    if errors:
        parts.append("\n---\n_Skipped sources: " + "; ".join(md_cell(e) for e in errors) + "_")
    return "\n".join(parts) + "\n"


# --------------------------------------------------------------------------- #
# CLI
# --------------------------------------------------------------------------- #
def main(argv=None):
    p = argparse.ArgumentParser(
        prog="render_markdown",
        description="Render a weekly-report JSON bundle into a faithful Markdown report.")
    p.add_argument("json_file", nargs="?", default="-",
                   help="path to the JSON bundle, or '-' for stdin (default)")
    p.add_argument("--output", "-o", help="write Markdown here (default: stdout)")
    p.add_argument("--title", help="report heading (default 'Weekly report')")
    args = p.parse_args(argv)

    try:
        if args.json_file == "-":
            bundle = json.load(sys.stdin)
        else:
            with open(args.json_file, "r", encoding="utf-8") as fh:
                bundle = json.load(fh)
    except (OSError, json.JSONDecodeError) as e:
        print(f"error: could not read JSON bundle: {e}", file=sys.stderr)
        return 1
    if not isinstance(bundle, dict):
        print("error: JSON bundle must be an object (from 'weekly_report.py gather')",
              file=sys.stderr)
        return 1

    doc = build_markdown(bundle, title=args.title)
    if args.output:
        try:
            with open(args.output, "w", encoding="utf-8") as fh:
                fh.write(doc)
        except OSError as e:
            print(f"error: could not write {args.output}: {e.strerror or e}",
                  file=sys.stderr)
            return 1
        print(args.output)
    else:
        sys.stdout.write(doc)
    return 0


if __name__ == "__main__":
    sys.exit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall