stackvitals 0.1.0__py3-none-any.whl

stackvitals/security/repo_checks.py

@@ -0,0 +1,132 @@
+"""Repo-level checks (Scorecard's Branch-Protection in tiers, Security-Policy, Signed-Releases and SBOM, Binary-Artifacts,
+Fuzzing and the Best Practices badge), each from what GitHub says; what the token can't read is "unknown", never a pass."""
+import re
+
+from stackvitals.ci.api import APIError
+
+# Scorecard's own list (checks/raw/binary_artifact.go), so the two agree on what a binary is.
+BINARY = re.compile(r"\.(crx|deb|dex|dey|elf|o|a|so|macho|iso|class|jar|bundle|dylib|lib|msi|dll|drv|efi|exe|ocx|pyc|pyo"
+                    r"|par|rpm|wasm|whl)$", re.I)
+GRADLE_WRAPPER = "gradle/wrapper/gradle-wrapper.jar"
+SIGNED = re.compile(r"\.(sig|asc|minisig|sigstore|sigstore\.json|intoto\.jsonl|pem)$", re.I)
+SBOM = re.compile(r"(sbom|\.spdx(\.json)?$|\.cdx\.(json|xml)$|cyclonedx|bom\.(json|xml)$)", re.I)
+BADGE_API = "https://www.bestpractices.dev/projects.json"
+POLICY = ("SECURITY.md", ".github/SECURITY.md", "docs/SECURITY.md", "SECURITY.rst", ".github/SECURITY.rst")
+# Real fuzzers only: ClusterFuzzLite, cargo-fuzz targets, libFuzzer sources. A folder merely named "fuzz" (scripts that
+# compare outputs) isn't one, as a side-by-side with Scorecard showed.
+FUZZ_PATHS = re.compile(r"(^|/)\.clusterfuzzlite/|(^|/)fuzz/(fuzz_targets/)?[^/]+\.rs$|_fuzzer\.(c|cc|cpp)$"
+                        r"|(^|/)fuzzers?/[^/]+_fuzzer\.(c|cc|cpp|go|py)$|fuzz[^/]*_test\.go$|(^|/)hfuzz_", re.I)
+
+
+def _try(api, path: str, params: dict | None = None):
+    try:
+        return api._get(path, params)
+    except APIError:
+        return None
+
+
+def branch_tiers(protection: dict | None, rules: list[dict] | None, summary: dict | None = None) -> dict:
+    """Scorecard's five tiers, each "met", "missing" or "unknown". Classic protection needs an admin token to read in
+    full; rulesets are readable by anyone who can read the repo; and the branch's public summary (GET branches/{b}) says
+    whether classic protection is on and which checks it requires, so without admin those two tiers are still known,
+    where Scorecard counts what it can't read as met."""
+    kinds = {r.get("type"): r.get("parameters") or {} for r in rules or [] if isinstance(r, dict)}
+    p = protection or {}
+    pr_rule = kinds.get("pull_request") or {}
+    classic_reviews = p.get("required_pull_request_reviews") or {}
+    count = classic_reviews.get("required_approving_review_count") or pr_rule.get("required_approving_review_count") or 0
+    owners = classic_reviews.get("require_code_owner_reviews") or pr_rule.get("require_code_owner_review")
+    stale = classic_reviews.get("dismiss_stale_reviews") or pr_rule.get("dismiss_stale_reviews_on_push")
+    full = protection is not None
+    s = ((summary or {}).get("protection") or {}) if summary else {}
+    classic_on = bool(s.get("enabled"))
+    checks = (s.get("required_status_checks") or {})
+    required = bool(checks.get("contexts") or checks.get("checks")) and checks.get("enforcement_level") != "off"
+
+    def tier(ok_full, ok_rules, ok_summary=None):
+        # Full classic settings decide; else rulesets; else the public summary; else nothing is known.
+        if full:
+            return "met" if ok_full else "missing"
+        if ok_rules:
+            return "met"
+        if ok_summary is not None:
+            return "met" if ok_summary else "missing"
+        # Classic protection is on but unreadable without admin: it may hold this rule, so it isn't called missing.
+        return "missing" if rules and not classic_on else "unknown"
+    tiers = [
+        ("no force pushes or deletion", tier(not (p.get("allow_force_pushes") or {}).get("enabled", True)
+                                             and not (p.get("allow_deletions") or {}).get("enabled", True),
+                                             "non_fast_forward" in kinds and "deletion" in kinds,
+                                             # Classic protection blocks both unless an admin allowed them.
+                                             True if classic_on else None)),
+        ("reviews required", tier(bool(classic_reviews) and count >= 1, bool(pr_rule) and count >= 1)),
+        ("status checks required", tier(bool(p.get("required_status_checks")), "required_status_checks" in kinds,
+                                        required if summary else None)),
+        ("two reviewers and code owners", tier(count >= 2 and bool(owners), count >= 2 and bool(owners))),
+        ("stale reviews dismissed, admins included", tier(bool(stale) and (p.get("enforce_admins") or {}).get("enabled"),
+                                                          bool(stale) and bool(rules))),
+    ]
+    known = full or bool(rules) or classic_on
+    out = [{"tier": i + 1, "rule": name, "state": state} for i, (name, state) in enumerate(tiers)]
+    met = 0
+    for t in out:
+        if t["state"] != "met":
+            break
+        met += 1
+    return {"tiers": out, "level": met, "readable": known}
+
+
+def policy(api, repo: str, owner: str) -> dict:
+    """SECURITY.md in the repo or the owner's .github repo, its contact and disclosure words; private reporting on."""
+    text, where = None, None
+    for repo_name, path in [(repo, p) for p in POLICY] + [(f"{owner}/.github", "SECURITY.md")]:
+        got = _try(api, f"/repos/{repo_name}/contents/{path}")
+        if isinstance(got, dict) and got.get("content"):
+            import base64
+            text, where = base64.b64decode(got["content"]).decode("utf-8", "replace"), f"{repo_name}:{path}"
+            break
+    reporting = _try(api, f"/repos/{repo}/private-vulnerability-reporting")
+    low = (text or "").lower()
+    return {"file": where, "contact": bool(re.search(r"@|https?://|security advisor", low)),
+            "disclosure": bool(re.search(r"disclos|vulnerab|days|report", low)),
+            "private_reporting": (reporting or {}).get("enabled") if isinstance(reporting, dict) else None}
+
+
+def releases(rels: list[dict]) -> dict:
+    """The last five releases' assets: signed or attested ones, and an SBOM among them."""
+    last = [r for r in rels or [] if not r.get("draft")][:5]
+    signed = [r.get("tag_name") for r in last if any(SIGNED.search(a.get("name") or "") for a in r.get("assets") or [])]
+    sbom = [r.get("tag_name") for r in last if any(SBOM.search(a.get("name") or "") for a in r.get("assets") or [])]
+    return {"releases": len(last), "signed": signed, "sbom": sbom}
+
+
+def tree_facts(paths: list[str]) -> dict:
+    """Committed binaries (Gradle's wrapper jar left out, as Scorecard leaves it), SBOM files and fuzzing setups."""
+    return {"binaries": sorted(p for p in paths if BINARY.search(p) and not p.endswith(GRADLE_WRAPPER))[:50],
+            "sbom_files": sorted(p for p in paths if SBOM.search(p.rsplit("/", 1)[-1]))[:10],
+            "fuzzing": sorted({p for p in paths if FUZZ_PATHS.search(p)})[:10]}
+
+
+# Executable file headers: ELF, Mach-O (both byte orders, fat), Windows PE.
+MAGIC = (b"\x7f\x45\x4c\x46", b"\xfe\xed\xfa\xce", b"\xfe\xed\xfa\xcf", b"\xce\xfa\xed\xfe", b"\xcf\xfa\xed\xfe", b"\xca\xfe\xba\xbe", b"MZ")
+MAX_SNIFF, SNIFF_BYTES = 10, 20_000_000
+
+
+def sniff_candidates(entries: list[dict]) -> list[dict]:
+    """Executable-mode files with no extension (where Scorecard's name list sees nothing), small enough to read."""
+    return [e for e in entries if e.get("type") == "blob" and e.get("mode") == "100755"
+            and "." not in e["path"].rsplit("/", 1)[-1] and 1024 <= (e.get("size") or 0) <= SNIFF_BYTES][:MAX_SNIFF]
+
+
+def is_executable(head: bytes) -> bool:
+    """Whether a file's first bytes are an executable's (a script starting with #! is not)."""
+    return any(head.startswith(m) for m in MAGIC)
+
+
+def badge(get_json, repo_url: str) -> str | None:
+    """The OpenSSF Best Practices badge level (passing, silver, gold) from bestpractices.dev, else None."""
+    try:
+        found = get_json(f"{BADGE_API}?url={repo_url}") or []
+    except Exception:  # noqa: BLE001 - a lookup that fails says nothing either way
+        return None
+    return (found[0] or {}).get("badge_level") if isinstance(found, list) and found else None

stackvitals/security/workflows.py

@@ -0,0 +1,111 @@
+"""Workflow checks (Scorecard's Dangerous-Workflow, Token-Permissions, Pinned-Dependencies, SAST and Packaging), read
+from the workflow files themselves. Unlike Scorecard, a checkout of fork code behind a guard (a label, an actor or an
+author-association test) is reported as guarded, not as a hole."""
+import re
+
+import yaml
+
+# Text an outsider controls; inside a run: script it can run commands (script injection).
+UNTRUSTED = re.compile(r"\$\{\{\s*(github\.event\.(issue\.(title|body)|pull_request\.(title|body|head\.ref|head\.label)"
+                       r"|comment\.body|review\.body|review_comment\.body|discussion\.(title|body)|head_commit\.(message|author\.(name|email))"
+                       r"|commits\[[^\]]*\]\.(message|author\.(name|email))|pages\[[^\]]*\]\.page_name|workflow_run\.(head_branch|display_title|head_commit\.message))"
+                       r"|github\.head_ref)\s*\}\}")
+FORK_REF = re.compile(r"github\.event\.pull_request\.head\.(sha|ref)|github\.head_ref|github\.event\.workflow_run\.head_(sha|branch)"
+                      r"|refs/pull/")
+GUARD = re.compile(r"labels|label\.name|github\.actor|author_association|github\.event\.pull_request\.head\.repo\.full_name\s*==|"
+                   r"github\.repository_owner|environment")
+PIN = re.compile(r"^[0-9a-f]{40}$")
+CURL_PIPE = re.compile(r"(curl|wget)\b[^|\n]*\|\s*(sudo\s+)?(ba|z|da)?sh\b")
+# Installs that take whatever version is newest (Scorecard's Pinned-Dependencies counts these too): pip without a
+# requirements file, a pinned version or hashes, and global npm installs without a version.
+PIP_LOOSE = re.compile(r"\bpip3?\s+install\s+(?!.*(-r\s|--requirement|--require-hashes|-e\s|\s\.(\s|$)|==))[^\n]*")
+NPM_GLOBAL = re.compile(r"\bnpm\s+(install|i)\s+(-g|--global)\s+(?![^\s@]+@\d)[^\n]*")
+FROM_LINE = re.compile(r"(?mi)^\s*FROM\s+(?:--platform=\S+\s+)?(\S+)")
+SAST = ("github/codeql-action", "semgrep", "sonarsource/sonarcloud", "snyk/actions", "returntocorp/semgrep")
+PUBLISH = re.compile(r"npm publish|pypa/gh-action-pypi-publish|twine upload|goreleaser|docker/build-push-action|cargo publish"
+                     r"|gem push|dotnet nuget push|gradle.*publish|mvn.*deploy|uv publish|poetry publish")
+
+
+def _load(text: str) -> dict | None:
+    try:
+        doc = yaml.safe_load(text)
+    except yaml.YAMLError:
+        return None
+    return doc if isinstance(doc, dict) else None
+
+
+def _events(doc: dict) -> set[str]:
+    on = doc.get("on", doc.get(True))  # YAML 1.1 reads a bare `on` as true
+    if isinstance(on, str):
+        return {on}
+    return set(on) if isinstance(on, (list, dict)) else set()
+
+
+def _steps(job: dict) -> list[dict]:
+    return [s for s in job.get("steps") or [] if isinstance(s, dict)]
+
+
+def check(path: str, text: str) -> list[dict]:
+    """Findings in one workflow file: {"probe", "path", "job", "line" text, "detail", "guarded"}."""
+    doc = _load(text)
+    if doc is None:
+        return []
+    out = []
+    events = _events(doc)
+    privileged = events & {"pull_request_target", "workflow_run"}
+    for name, job in (doc.get("jobs") or {}).items():
+        if not isinstance(job, dict):
+            continue
+        guard = str(job.get("if") or "")
+        for step in _steps(job):
+            uses, run, with_ = str(step.get("uses") or ""), str(step.get("run") or ""), step.get("with") or {}
+            if privileged and uses.startswith("actions/checkout") and FORK_REF.search(str(with_.get("ref") or "")):
+                why = GUARD.search(guard + " " + str(step.get("if") or ""))
+                out.append({"probe": "hasDangerousWorkflowUntrustedCheckout", "path": path, "job": name,
+                            "detail": f"{'/'.join(sorted(privileged))} checks out the pull request's code",
+                            "guarded": f"only when `{(guard or step.get('if'))}`" if why else None})
+            for m in UNTRUSTED.finditer(run):
+                out.append({"probe": "hasDangerousWorkflowScriptInjection", "path": path, "job": name, "detail": m.group(0),
+                            "guarded": None})
+            if uses and not uses.startswith(("./", "docker://")) and "@" in uses and not PIN.match(uses.rsplit("@", 1)[1]):
+                out.append({"probe": "pinsDependencies", "path": path, "job": name, "detail": uses, "guarded": None})
+            for rx in (CURL_PIPE, PIP_LOOSE, NPM_GLOBAL):
+                if (m := rx.search(run)):
+                    out.append({"probe": "pinsDependencies", "path": path, "job": name, "detail": m.group(0).strip()[:120],
+                                "guarded": None})
+    top = doc.get("permissions")
+    if top is None or top == "write-all" or (isinstance(top, dict) and any(v == "write" for v in top.values())):
+        jobs_ok = all(isinstance(j, dict) and j.get("permissions") is not None for j in (doc.get("jobs") or {}).values())
+        if not (top is None and jobs_ok):
+            out.append({"probe": "topLevelPermissions", "path": path, "job": None,
+                        "detail": "no top-level permissions (the token gets the repo's default)" if top is None
+                        else f"top-level permissions: {top}", "guarded": None})
+    return out
+
+
+def dockerfile(path: str, text: str) -> list[dict]:
+    """Base images used by tag rather than digest (FROM image:tag, not image@sha256:...); scratch and earlier build
+    stages left out."""
+    stages, out = set(), []
+    for line in (text or "").splitlines():
+        m = FROM_LINE.match(line)
+        if not m:
+            continue
+        image = m.group(1)
+        alias = line.split()[-1].lower() if " as " in line.lower() else None
+        if image.lower() != "scratch" and image.lower() not in stages and "@sha256:" not in image:
+            out.append({"probe": "pinsDependencies", "path": path, "job": None, "detail": f"FROM {image}", "guarded": None})
+        if alias:
+            stages.add(alias)
+    return out
+
+
+def uses_any(text: str, names) -> bool:
+    low = (text or "").lower()
+    return any(n in low for n in names)
+
+
+def facts(files: dict[str, str]) -> dict:
+    """What the workflows say about SAST and publishing: {"sast": [paths], "publish": [paths]}."""
+    return {"sast": sorted(p for p, t in files.items() if uses_any(t, SAST)),
+            "publish": sorted(p for p, t in files.items() if PUBLISH.search(t or ""))}

stackvitals/shell.py

@@ -0,0 +1,107 @@
+"""One look for every module's static page: the header, the styles, table search and trend charts drawn from tables."""
+import html
+from pathlib import Path
+
+MODULES = (("ci.html", "CI health"), ("flow.html", "Team Flow"), ("delivery.html", "Delivery"), ("insights.html", "Insights"),
+           ("community.html", "Community"), ("portal.html", "Portal"), ("explore.html", "Explore"))
+# Each printable page's section in the app (index.html#/<route>).
+APP_ROUTES = {"ci.html": "ci", "flow.html": "prs", "delivery.html": "delivery", "insights.html": "insights",
+              "community.html": "community", "portal.html": "portal", "explore.html": "explore"}
+# Pinned with its integrity hash (from cdnjs), so a changed file never runs; without it the tables still show the numbers.
+CHART_JS = "https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.5.1/chart.umd.min.js"
+CHART_SRI = "sha512-WoViKhKD4qI2WruSZqv9+kvM4WfFhUMQCLN4QlDTt5aU56fLQy2gYoxWIqlEnXqJy/+Ac5q/hk1oWfqnMDhwMA=="
+
+CSS = """:root{color-scheme:light dark;--bg:#fff;--fg:#1f2328;--mut:#59636e;--line:#d1d9e0;--bad:#cf222e;--warn:#9a6700;--ok:#1a7f37;--card:#f6f8fa;--link:#0969da;--c1:#0969da;--c2:#bf3989;--c3:#1a7f37}
+@media (prefers-color-scheme:dark){:root{--bg:#0d1117;--fg:#e6edf3;--mut:#9198a1;--line:#3d444d;--bad:#ff7b72;--warn:#d29922;--ok:#3fb950;--card:#151b23;--link:#4493f8;--c1:#4493f8;--c2:#db61a2;--c3:#3fb950}}
+body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}a{color:var(--link)}
+.top{border-bottom:1px solid var(--line);background:var(--card)}.top nav{max-width:1100px;margin:0 auto;padding:10px 16px;display:flex;flex-wrap:wrap;gap:4px 18px;align-items:center}
+.top a.app{margin-left:auto}.top b{margin-right:6px}.top a{text-decoration:none;padding:2px 0}.top a[aria-current]{color:var(--fg);font-weight:600;border-bottom:2px solid var(--c1)}
+main{max-width:1100px;margin:0 auto;padding:20px 16px}h1{font-size:22px;margin:0 0 4px;overflow-wrap:anywhere}h2{font-size:17px;margin:28px 0 8px}
+.mut{color:var(--mut)}.cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:12px;margin-top:16px}
+.card{background:var(--card);border:1px solid var(--line);border-radius:8px;padding:10px 12px}.card b{display:block;font-size:20px}
+.tbl{overflow-x:auto}table{border-collapse:collapse;width:100%;font-size:14px}th,td{text-align:left;padding:6px 8px;border-bottom:1px solid var(--line);vertical-align:top}
+th{color:var(--mut);font-weight:600}td{overflow-wrap:break-word}.tag{font-size:12px;padding:1px 7px;border-radius:10px;border:1px solid currentColor;white-space:nowrap}
+.nw{white-space:nowrap}.flaky,.broken{color:var(--bad)}.suspect{color:var(--warn)}.fixed,.ok{color:var(--ok)}footer{margin-top:32px;font-size:13px}
+.find-bar{display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin:4px 0 8px}.find-bar input,.find-bar select{font:inherit;color:var(--fg);background:var(--bg);border:1px solid var(--line);border-radius:6px;padding:4px 8px}
+.find-bar input{flex:1 1 200px;max-width:320px}.charts{display:grid;grid-template-columns:repeat(auto-fit,minmax(320px,1fr));gap:16px}
+.chart{margin:0;border:1px solid var(--line);border-radius:8px;padding:10px 12px;min-width:0}.chart figcaption{font-weight:600;margin-bottom:6px}
+.chart .box{position:relative;height:220px;display:none}.chart.drawn .box{display:block}.chart summary{color:var(--mut);font-size:13px;cursor:pointer}"""
+
+# Plain JavaScript: a search box (and a filter for marked columns) on long tables, then each chart drawn from its table.
+SCRIPT = r"""<script>(function(){
+function rows(t){return [].filter.call(t.rows,function(r){return !r.querySelector('th')})}
+function find(t){var body=rows(t);if(body.length<6)return;
+var bar=document.createElement('div');bar.className='find-bar';
+var q=document.createElement('input');q.type='search';q.placeholder='Filter rows';q.setAttribute('aria-label','Filter rows');bar.appendChild(q);
+var picks=[];[].forEach.call(t.rows[0].cells,function(h,i){if(!h.hasAttribute('data-filter'))return;
+var s=document.createElement('select'),seen={};s.setAttribute('aria-label','Filter by '+h.textContent);s.add(new Option('Any '+h.textContent.toLowerCase(),''));
+body.forEach(function(r){var v=r.cells[i]?r.cells[i].textContent.trim():'';if(v&&!seen[v]){seen[v]=1;s.add(new Option(v,v))}});
+picks.push([s,i]);bar.appendChild(s)});
+var n=document.createElement('span');n.className='mut';n.setAttribute('aria-live','polite');bar.appendChild(n);
+function apply(){var w=q.value.trim().toLowerCase(),shown=0;body.forEach(function(r){
+var ok=!w||r.textContent.toLowerCase().indexOf(w)>=0;picks.forEach(function(p){if(p[0].value&&(r.cells[p[1]]?r.cells[p[1]].textContent.trim():'')!==p[0].value)ok=false});
+r.hidden=!ok;shown+=ok?1:0});n.textContent=shown+' of '+body.length+' rows'}
+q.addEventListener('input',apply);picks.forEach(function(p){p[0].addEventListener('change',apply)});
+var at=t.closest('.tbl')||t;at.parentNode.insertBefore(bar,at);apply()}
+function draw(){if(!window.Chart)return;var cs=getComputedStyle(document.documentElement),v=function(k){return cs.getPropertyValue(k).trim()};
+Chart.defaults.color=v('--mut');Chart.defaults.borderColor=v('--line');Chart.defaults.font.family=getComputedStyle(document.body).fontFamily;
+var colors=[v('--c1'),v('--c2'),v('--c3')];
+document.querySelectorAll('figure[data-chart]').forEach(function(f){var t=f.querySelector('table'),body=rows(t),head=[].slice.call(t.rows[0].cells,1);
+var sets=head.map(function(h,i){var c=colors[i%colors.length];return{label:h.textContent,borderColor:c,backgroundColor:c,spanGaps:false,cubicInterpolationMode:'monotone',pointRadius:2,
+data:body.map(function(r){var x=r.cells[i+1].getAttribute('data-v');return x===null||x===''?null:+x}),text:body.map(function(r){return r.cells[i+1].textContent})}});
+f.classList.add('drawn');try{new Chart(f.querySelector('canvas'),{type:f.getAttribute('data-chart'),data:{labels:body.map(function(r){return r.cells[0].textContent}),datasets:sets},
+options:{animation:false,maintainAspectRatio:false,interaction:{mode:'index',intersect:false},scales:{y:{beginAtZero:true,title:{display:!!f.dataset.y,text:f.dataset.y}}},
+plugins:{legend:{display:sets.length>1},tooltip:{callbacks:{label:function(c){return c.dataset.label+': '+c.dataset.text[c.dataIndex]}}}}}});
+f.querySelector('details').open=false}catch(e){f.classList.remove('drawn')}})}
+document.addEventListener('DOMContentLoaded',function(){document.querySelectorAll('table.find').forEach(find);draw()})})()</script>"""
+
+
+def present(docs: Path) -> set[str]:
+    """The module pages (and the app) already in this docs folder, so the header never links to a page that isn't there."""
+    return {name for name in [*(m for m, _ in MODULES), "index.html"] if (Path(docs) / name).exists()}
+
+
+def nav(current: str | None, pages=(), root: str = "", app_route: str | None = None) -> str:
+    links = []
+    for name, label in MODULES:
+        if name == current:
+            links.append(f"<a href='{root}{name}' aria-current=page>{label}</a>")
+        elif name in pages:
+            links.append(f"<a href='{root}{name}'>{label}</a>")
+    # These pages are the printable view; the app (index.html, when it's beside them) is where the decisions live.
+    route = html.escape(app_route if app_route is not None else APP_ROUTES.get(current, ""), quote=True)
+    app = "index.html" in pages
+    brand = f"<a href='{root}index.html'>StackVitals</a>" if app else "StackVitals"
+    return (f"<header class=top><nav aria-label='StackVitals pages'><b>{brand}</b>{''.join(links)}"
+            + (f"<a class=app href='{root}index.html#/{route}'>Open in the app</a>" if app else "") + "</nav></header>")
+
+
+def page(title: str, repo: str, current: str | None, sub: str, body: str, pages=(), root: str = "",
+         app_route: str | None = None) -> str:
+    """A whole page; `sub` and `body` are HTML the caller already escaped."""
+    e = html.escape
+    charts = (f"<script defer src='{CHART_JS}' integrity='{CHART_SRI}' crossorigin=anonymous referrerpolicy=no-referrer></script>"
+              if "data-chart=" in body else "")
+    return (f"<!doctype html><html lang=en><head><meta charset=utf-8><meta name=viewport content='width=device-width,initial-scale=1'>"
+            f"<title>{e(title)}: {e(repo)}</title><style>{CSS}</style>{charts}</head><body>{nav(current, pages, root, app_route)}<main>"
+            f"<h1>{e(title)}: {e(repo)}</h1>" + (f"<div class=mut>{sub}</div>" if sub else "") + body + f"</main>{SCRIPT}</body></html>")
+
+
+def _v(value) -> str:
+    return "" if value is None else str(value)
+
+
+def chart(title: str, x: str, labels: list[str], series: list[tuple[str, list]], y: str = "", fmt=str, kind: str = "line") -> str:
+    """A chart drawn in the browser from the table below it, so its points are the table's numbers; no JavaScript, the table."""
+    e = html.escape
+    head = f"<tr><th>{e(x)}</th>" + "".join(f"<th>{e(name)}</th>" for name, _ in series) + "</tr>"
+    rows = "".join(f"<tr><td>{e(str(label))}</td>" + "".join(
+        f"<td data-v='{_v(values[i])}'>{e('-' if values[i] is None else fmt(values[i]))}</td>" for _, values in series) + "</tr>"
+        for i, label in enumerate(labels))
+    return (f"<figure class=chart data-chart={kind} data-y='{e(y)}'><figcaption>{e(title)}</figcaption>"
+            f"<div class=box><canvas role=img aria-label='{e(title)}'></canvas></div>"
+            f"<details open><summary>Numbers</summary><div class=tbl><table>{head}{rows}</table></div></details></figure>")
+
+
+def charts(figures: list[str]) -> str:
+    return f"<div class=charts>{''.join(figures)}</div>" if figures else ""

stackvitals/site.py

@@ -0,0 +1,51 @@
+"""The project site: a static landing page, the app itself (app.html: Welcome and Setup on first open, ?demo=1 for three
+example repos) and, given a repo's docs folder, that repo's real data under demo/, built from the package into one static
+folder (`stackvitals site build --out DIR --demo DOCS`)."""
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+from stackvitals.ci.cli import ACTION_REF
+from stackvitals.core.webapp import files, site_files, stamped, write_webapp
+
+REAL_DEMO = b"<!--REAL-DEMO-->"
+
+
+def build(out: Path, demo: Path | None = None, ref: str = ACTION_REF) -> list[str]:
+    """Write the site into `out`: index.html (landing), app.html and app/ (the app), setup.html and integrations.html
+    (forwards from the earlier site's addresses), site/ styles, and demo/ (the app on a copy of `demo`, a docs folder).
+    `ref` is kept for the command line; the app's Setup writes the workflow with the release it was built for."""
+    out = Path(out)
+    app = files()
+    pages = {**{name: data for name, data in app.items() if name != "index.html"}, "app.html": app["index.html"], **site_files()}
+    link = b'<a class="btn big" href="demo/">A real repo\'s data</a>' if demo else b""
+    pages["index.html"] = pages["index.html"].replace(REAL_DEMO, link)
+    for name, data in stamped(pages).items():
+        target = out / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
+    if demo:
+        target = out / "demo"
+        if target.exists():
+            shutil.rmtree(target)
+        shutil.copytree(demo, target, ignore=shutil.ignore_patterns("app", "index.html"))
+        write_webapp(target)
+    return sorted(pages)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="stackvitals site", description="Build the StackVitals project site.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    b = sub.add_parser("build", help="landing page, the app and an optional real-data demo into one folder")
+    b.add_argument("--out", required=True, help="folder to write")
+    b.add_argument("--demo", help="a repo's docs folder (from its stackvitals-data branch) to show as a real-data demo")
+    b.add_argument("--ref", default=ACTION_REF, help=argparse.SUPPRESS)  # kept so older build scripts still run
+    args = parser.parse_args(argv)
+    demo = Path(args.demo) if args.demo else None
+    if demo and not (demo / "app.json").exists():
+        print(f"{demo} has no app.json; give the docs folder of a repo's stackvitals-data branch.", file=sys.stderr)
+        return 2
+    written = build(Path(args.out), demo, args.ref)
+    print(f"Site written to {args.out} ({len(written)} files{', with a real-data demo' if demo else ''}).")
+    return 0