stackvitals 0.1.0__py3-none-any.whl

stackvitals/core/uicli.py

@@ -0,0 +1,138 @@
+"""`stackvitals ui owner/repo`: a repo's StackVitals pages on your machine, Explore included, from a local copy of its
+stackvitals-data branch. Private repos and self-hosters get the full dashboard without Pages; nothing is served beyond
+127.0.0.1."""
+import argparse
+import base64
+import functools
+import os
+import subprocess
+import sys
+import webbrowser
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from stackvitals.ci import cli as ci_cli
+from stackvitals.ci.action import BRANCH
+
+
+class _Quiet(SimpleHTTPRequestHandler):
+    def log_message(self, *args):  # one line per file would bury the address
+        pass
+
+
+def _git(args: list[str], tok: str | None, remote: str | None) -> subprocess.CompletedProcess:
+    # The token goes in a header for this one command, through its environment: never the copy's config or the process list.
+    env = None
+    if tok and not remote:
+        basic = base64.b64encode(f"x-access-token:{tok}".encode()).decode()
+        env = dict(os.environ)
+        try:
+            n = int(env.get("GIT_CONFIG_COUNT") or 0)
+        except ValueError:
+            n = 0
+        env.update({"GIT_CONFIG_COUNT": str(n + 1), f"GIT_CONFIG_KEY_{n}": "http.extraheader",
+                    f"GIT_CONFIG_VALUE_{n}": f"AUTHORIZATION: basic {basic}"})
+    return subprocess.run(["git", *args], capture_output=True, text=True, env=env)
+
+
+def fetch(repo: str, tok: str | None, folder: Path, remote: str | None = None) -> Path:
+    """A shallow copy of the data branch in `folder`, brought up to date (the branch may have been squashed and
+    force-pushed, so the copy follows it rather than merging)."""
+    folder = Path(folder)
+    url = remote or f"https://github.com/{repo}.git"
+    if (folder / ".git").is_dir():
+        done = _git(["-C", str(folder), "fetch", "--depth", "1", url, BRANCH], tok, remote)
+        if done.returncode == 0:
+            _git(["-C", str(folder), "reset", "--hard", "FETCH_HEAD"], None, None)
+            return folder
+    folder.parent.mkdir(parents=True, exist_ok=True)
+    done = _git(["clone", "--quiet", "--depth", "1", "--branch", BRANCH, "--single-branch", url, str(folder)], tok, remote)
+    if done.returncode != 0:
+        raise RuntimeError(f"no {BRANCH} branch to read in {repo} (does StackVitals run there, and can your token read it?)")
+    return folder
+
+
+def serve(folder: Path, port: int = 0) -> ThreadingHTTPServer:
+    return ThreadingHTTPServer(("127.0.0.1", port), functools.partial(_Quiet, directory=str(folder)))
+
+
+def first_page(docs: Path) -> str | None:
+    """The page to open: the app's home when there is one, else the first module page the branch has (Portal alone too)."""
+    from stackvitals import shell
+    return next((p for p in ("index.html", *(name for name, _ in shell.MODULES)) if (Path(docs) / p).is_file()), None)
+
+
+def _run_job(argv: list[str], env: dict) -> int:
+    # The Action's own job, in this process, with the environment a GitHub run would have.
+    import os
+    from stackvitals.ci.cli import action_main
+    saved = dict(os.environ)
+    os.environ.update(env)
+    try:
+        return action_main(argv)
+    finally:
+        os.environ.clear()
+        os.environ.update(saved)
+
+
+def collect_locally(repo: str, tok: str | None, home: Path, days: int = 90) -> str:
+    """Runs the Action's job on this machine into a local data branch (a bare repo under `home`), reading GitHub with the
+    given token and never writing to it. Returns the local remote's URL."""
+    import tempfile
+    bare = Path(home) / "local" / f"{repo.replace('/', '__')}.git"
+    if not (bare / "HEAD").exists():
+        bare.parent.mkdir(parents=True, exist_ok=True)
+        subprocess.run(["git", "init", "-q", "--bare", str(bare)], check=True)
+    env = {"GITHUB_REPOSITORY": repo, "STACKVITALS_TOKEN": tok or "", "GITHUB_TOKEN": tok or "", "STACKVITALS_REMOTE": str(bare),
+           "GITHUB_EVENT_NAME": "schedule", "STACKVITALS_READ_ONLY": "1", "RUNNER_TEMP": tempfile.mkdtemp(prefix="stackvitals-")}
+    code = _run_job(["--modules", "ci,flow", "--days", str(days), "--pr-comments", "false"], env)
+    if code:
+        raise RuntimeError(f"the local run ended with code {code}")
+    # A plain path, not a file:// URL: Git Bash setups that skip path conversion misread file:///C:/... addresses.
+    return str(bare)
+
+
+def main(argv: list[str] | None = None, tok: str | None = None, home: Path | None = None, open_browser=webbrowser.open) -> int:
+    parser = argparse.ArgumentParser(prog="stackvitals ui", description="Open a repo's StackVitals pages from a local copy.")
+    parser.add_argument("repo", help="owner/name")
+    parser.add_argument("--port", type=int, default=0, help="port on 127.0.0.1 (default: any free one)")
+    parser.add_argument("--no-open", action="store_true", help="print the address instead of opening a browser")
+    parser.add_argument("--remote", help=argparse.SUPPRESS)  # another place to clone from (tests, mirrors)
+    parser.add_argument("--collect", action="store_true",
+                        help="no StackVitals in the repo? read its history on this machine first (no Action, no server; nothing is written to GitHub)")
+    parser.add_argument("--days", type=int, default=90, help="with --collect: days of history to read")
+    args = parser.parse_args(argv)
+    tok = tok if tok is not None else (None if args.remote else ci_cli.token())
+    folder = Path(home or ci_cli.home()) / "ui" / args.repo.replace("/", "__")
+    if args.collect and not args.remote:
+        print(f"Reading {args.repo}'s history on this machine (a few minutes; nothing is written to GitHub)...", flush=True)
+        try:
+            args.remote = collect_locally(args.repo, tok, Path(home or ci_cli.home()), args.days)
+        except Exception as exc:  # noqa: BLE001 - say what went wrong instead of a traceback
+            print(f"Could not read {args.repo}: {exc}", file=sys.stderr)
+            return 1
+    try:
+        fetch(args.repo, tok, folder, remote=args.remote)
+    except RuntimeError as exc:
+        print(f"Could not open {args.repo}: {exc}", file=sys.stderr)
+        return 1
+    if (folder / "docs").is_dir():
+        # This install's app, not the copy the branch was last written with (a branch may lag a release or two).
+        from stackvitals.core.webapp import write_webapp
+        write_webapp(folder / "docs")
+    page = first_page(folder / "docs")
+    if page is None:
+        print(f"{args.repo}'s {BRANCH} branch has no pages yet.", file=sys.stderr)
+        return 1
+    server = serve(folder, args.port)
+    url = f"http://127.0.0.1:{server.server_port}/docs/{page}"
+    print(f"StackVitals for {args.repo}: {url} (Explore: /docs/explore.html). Ctrl+C to stop.", flush=True)
+    if not args.no_open:
+        open_browser(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0

stackvitals/core/webapp.py

@@ -0,0 +1,79 @@
+"""The StackVitals app, one static page over every module, copied beside the pages at the end of every job: index.html is
+the app (built from web/ into the package's web/index.html and web/app/; the CI page is ci.html), each file is written
+only when it changed, so a quiet run commits nothing, and app files the package no longer carries are removed."""
+import hashlib
+import re
+from importlib import resources
+from pathlib import Path
+
+APP_DIR = "app"
+TEXT = (".js", ".mjs", ".css", ".html", ".md", ".json", ".txt", ".svg")
+# Relative module imports in the app's scripts (static, side-effect and dynamic), and the page's links to its scripts and styles.
+IMPORTS = re.compile(rb"""(\bfrom\s*["']|\bimport\s*\(?\s*["'])(\.{1,2}/[^"'?]+\.m?js)(?=["'])""")
+LINKS = re.compile(rb"""((?:href|src)=")((?:app|site)/[^"?]+\.(?:m?js|css))(?=")""")
+WEB = resources.files("stackvitals") / "web"
+# The project site (landing page and forwards to the app) lives beside the app in the package but never goes to a repo's Pages.
+SITE_SOURCE = Path(str(WEB / "site"))
+
+
+def _walk(node, prefix: str, out: dict, skip=()) -> dict:
+    for child in node.iterdir():
+        if child.name.startswith((".", "__")) or child.name in skip:
+            continue
+        if child.is_dir():
+            _walk(child, f"{prefix}{child.name}/", out)
+        else:
+            out[prefix + child.name] = child.read_bytes()
+    return out
+
+
+def files() -> dict[str, bytes]:
+    """The app's files from the package, by their path under docs/."""
+    return _walk(WEB, "", {}, skip=("site",))
+
+
+def site_files() -> dict[str, bytes]:
+    """The project site's own files: its pages at the root, its styles under site/."""
+    return {(name if name.endswith(".html") else f"site/{name}"): data for name, data in _walk(WEB / "site", "", {}).items()}
+
+
+def stamped(app: dict[str, bytes]) -> dict[str, bytes]:
+    """Every app URL gets `?v=` + a hash of all the files, so a browser never mixes a cached release with a new one."""
+    # Text files lose a Windows checkout's CRLF; fonts and other binaries are kept byte for byte.
+    norm = {k: v.replace(b"\r\n", b"\n") if k.endswith(TEXT) else v for k, v in app.items()}
+    digest = hashlib.sha256(b"".join(k.encode() + b"\0" + norm[k] + b"\0" for k in sorted(norm))).hexdigest()[:10]
+    tag = rb"\1\2?v=" + digest.encode()
+    out = {}
+    for name, data in norm.items():
+        if name.endswith((".js", ".mjs")):
+            data = IMPORTS.sub(tag, data)
+        elif name.endswith(".html"):
+            data = LINKS.sub(tag, data)
+        out[name] = data
+    return out
+
+
+def write_webapp(docs: Path) -> list[str]:
+    """Copy the app into docs/ and return the paths that changed."""
+    docs = Path(docs)
+    wanted = stamped(files())
+    changed = []
+    same = lambda a, b: a.replace(b"\r\n", b"\n") == b.replace(b"\r\n", b"\n")  # a Windows checkout turns LF into CRLF
+    for rel, data in sorted(wanted.items()):
+        target = docs / rel
+        if target.is_file() and same(target.read_bytes(), data):
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
+        changed.append(rel)
+    app = docs / APP_DIR
+    if app.is_dir():
+        # The earlier app's files (views/, vendor/, old fonts) go too, so an upgraded site carries only this release.
+        for path in sorted(app.rglob("*"), reverse=True):
+            rel = path.relative_to(docs).as_posix()
+            if path.is_file() and rel not in wanted:
+                path.unlink()
+                changed.append(rel)
+            elif path.is_dir() and not any(path.iterdir()):
+                path.rmdir()
+    return changed

stackvitals/core/what_changed.py

@@ -0,0 +1,76 @@
+"""What changed before an incident: the deployments in the 72 hours before it began and the pull requests merged in
+that time (each with the deployment that shipped it), config and dependency changes called out, ranked so the likeliest
+cause comes first: the incident's own (or the last) deployment, a pull request a revert undid, then closeness in time."""
+import re
+from datetime import datetime, timedelta
+
+from stackvitals.core.ai_outcomes import is_revert, revert_target
+
+WINDOW_HOURS = 72
+MAX_CANDIDATES = 15
+DEPENDENCY = re.compile(r"(^|/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|poetry\.lock|uv\.lock|Pipfile\.lock|"
+                        r"requirements[^/]*\.txt|go\.(mod|sum)|Cargo\.(lock|toml)|Gemfile(\.lock)?|composer\.(json|lock)|"
+                        r"packages\.lock\.json|gradle\.lockfile|pom\.xml|package\.json|pyproject\.toml)$")
+CONFIG = re.compile(r"(^|/)(\.github/workflows/|Dockerfile|docker-compose[^/]*\.ya?ml$|[^/]+\.tf$|helm/|k8s/|kubernetes/|"
+                    r"deploy/|config/|\.env\.example$|[^/]+\.(toml|ini|cfg|conf)$)")
+
+
+def _t(text: str) -> datetime:
+    return datetime.fromisoformat(text.replace("Z", "+00:00"))
+
+
+def _kind(paths: list[str]) -> str:
+    if any(DEPENDENCY.search(p) for p in paths):
+        return "dependency"
+    if any(CONFIG.search(p) for p in paths):
+        return "config"
+    return "pr"
+
+
+def timeline(incident: dict, rows: list, deps: list[dict], hours: int = WINDOW_HOURS) -> dict:
+    """{"incident", "window_hours", "candidates": [{"kind", "ref", "at", "why", "deployment"}]}, likeliest first."""
+    start = _t(incident["created"])
+    since = start - timedelta(hours=hours)
+    within = lambda when: bool(when) and since <= _t(when) < start  # noqa: E731
+    shipped = [d for d in deps if within(d.get("finished"))]
+    own = incident.get("deployment")
+    last = max(shipped, key=lambda d: d["finished"])["id"] if shipped else None
+    by_number = {p["n"]: p for p, _ph, _d in rows}
+    reverted = {n for p, _ph, _d in rows if is_revert(p) and (n := revert_target(p, by_number)) is not None}
+    near = lambda when: 1 - (start - _t(when)).total_seconds() / (hours * 3600)  # noqa: E731
+    out = []
+    for d in shipped:
+        mine = d["id"] == own or (own is None and d["id"] == last)
+        out.append({"kind": "deployment", "ref": f"deployment {(d.get('sha') or '')[:7] or d['id']}", "at": d["finished"],
+                    "deployment": d["id"],
+                    "why": "the deployment this incident is tied to" if d["id"] == own else
+                           "the last deployment before it began" if d["id"] == last else "deployed in the window",
+                    "rank": 100 if mine else 40 + 20 * near(d["finished"])})
+    for p, _ph, d in rows:
+        if not within(p.get("mg")) or is_revert(p):
+            continue
+        kind = _kind(p.get("paths") or [])
+        why = []
+        rank = 30 * near(p["mg"])
+        if p["n"] in reverted:
+            why.append("later reverted")
+            rank += 60
+        if d and d["id"] in (own, last):
+            why.append("shipped in that deployment")
+            rank += 40
+        if kind != "pr":
+            why.append(f"changes {'dependencies' if kind == 'dependency' else 'configuration'}")
+            rank += 5
+        out.append({"kind": kind, "ref": f"#{p['n']}", "at": p["mg"], "deployment": d["id"] if d else None,
+                    "why": "; ".join(why) or "merged in the window", "rank": rank, "title": (p.get("ti") or "")[:120]})
+    out.sort(key=lambda c: -c["rank"])
+    return {"incident": {k: incident.get(k) for k in ("source", "number", "created", "resolved", "deployment")},
+            "window_hours": hours, "candidates": [{k: v for k, v in c.items() if k != "rank"} for c in out[:MAX_CANDIDATES]]}
+
+
+def recent(incidents: list[dict], rows: list, deps: list[dict], now: datetime, days: int = 90, most: int = 10) -> list[dict]:
+    """A timeline for each incident that began in the last `days`, newest first."""
+    floor = now - timedelta(days=days)
+    fresh = sorted((i for i in incidents if i.get("created") and _t(i["created"]) >= floor), key=lambda i: i["created"],
+                   reverse=True)
+    return [timeline(i, rows, deps) for i in fresh[:most]]

stackvitals/core/workspace.py

@@ -0,0 +1,194 @@
+"""One checkout of the data branch per job: every module writes into it, there is one commit, and what must happen only
+after the commit (re-runs, comments, issues, alerts) runs afterwards. A rejected push (another run got there first)
+re-runs every step on the fresh data, so overlapping runs converge and nothing is lost."""
+import os
+import shutil
+import stat
+import tempfile
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from stackvitals.ci.action import BRANCH, DataBranch, GitError
+from stackvitals.core.store import DEFAULT_CAP_MB, SQUASH_EVERY, STREAMS, HistoryStore
+
+RETRIES = 3
+
+
+def _rmtree(path: Path) -> None:
+    # Git leaves read-only files on Windows; clear the bit and retry so no clone is left behind.
+    def onerror(fn, p, _exc):
+        try:
+            os.chmod(p, stat.S_IWRITE)
+            fn(p)
+        except OSError:
+            pass
+    shutil.rmtree(path, onerror=onerror)
+
+
+class Workspace:
+    def __init__(self, env: dict, now: datetime | None = None):
+        self.env = env
+        self.now = now or datetime.now(timezone.utc)
+        self.repo = env["GITHUB_REPOSITORY"]
+        token = env.get("STACKVITALS_TOKEN") or env.get("GITHUB_TOKEN")
+        self.remote = env.get("STACKVITALS_REMOTE") or f"https://x-access-token:{token}@github.com/{self.repo}.git"
+        temp_root = env.get("RUNNER_TEMP")
+        if temp_root:
+            Path(temp_root).mkdir(parents=True, exist_ok=True)
+        self.work = Path(tempfile.mkdtemp(prefix="stackvitals-", dir=temp_root))
+        self.branch: DataBranch | None = None
+        self.hooks: list[tuple[str, object]] = []
+        self.notes: list[str] = []
+        # Side effects already done on GitHub in this job (a settings commit), kept when a rejected push retries the steps.
+        self.memo: dict = {}
+        self.results: dict = {}
+        # Data one step loaded and a later step may reuse, for this attempt only.
+        self.cache: dict = {}
+
+    @property
+    def path(self) -> Path:
+        return self.branch.path
+
+    def open(self, attempt: int = 0) -> None:
+        # Hooks registered during a rejected attempt are dropped: the steps run again and register them again.
+        self.hooks = []
+        self.cache = {}
+        from stackvitals.core.bucket import from_env
+        # A bucket when STACKVITALS_STORAGE names one (s3://...), else the stackvitals-data branch.
+        self.branch = from_env(self.env, self.work / f"data{attempt}") or DataBranch(self.remote, BRANCH, self.work / f"data{attempt}")
+        self.branch.open()
+
+    def after_commit(self, fn, label: str = "", first: bool = False) -> None:
+        # first: the job summary opens with it (what to fix first), whichever step registered it.
+        if first:
+            self.hooks.insert(0, (label, fn))
+        else:
+            self.hooks.append((label, fn))
+
+    def commit(self, message: str) -> str:
+        return self.branch.commit_push(message)
+
+    def run_hooks(self) -> None:
+        for label, fn in self.hooks:
+            try:
+                fn()
+            except Exception as exc:  # noqa: BLE001
+                # The data is committed by now; a chat service or a comment refusal must not fail the run.
+                self.notes.append(f"{label}: {exc}")
+
+    def close(self) -> None:
+        _rmtree(self.work)
+
+
+def housekeeping(ws: Workspace) -> dict:
+    """Retention per stream, the size cap, and the commit counter; all tunable through the Action's inputs."""
+    env, store = ws.env, HistoryStore(ws.path)
+    today = ws.now.date().isoformat()
+    days = {}
+    if env.get("STACKVITALS_RETENTION_DAYS"):
+        days.update({s: int(env["STACKVITALS_RETENTION_DAYS"]) for s in STREAMS if s != "ci/days"})
+    if env.get("STACKVITALS_CI_RETENTION_DAYS"):
+        days["ci/days"] = int(env["STACKVITALS_CI_RETENTION_DAYS"])
+    removed = store.retention(today, days)
+    cap_mb = float(env.get("STACKVITALS_SIZE_CAP_MB") or DEFAULT_CAP_MB)
+    dropped = store.cap(today, int(cap_mb * 1024 * 1024))
+    commits = store.bump_commits() if ws.branch.dirty() else int(store.meta().get("commits") or 0)
+    return {"removed": removed, "dropped": dropped, "commits": commits, "squashed": False}
+
+
+# The steps that write summary/ files, which the Explore page reads.
+SUMMARY_STEPS = ("CI Health", "Team Flow")
+
+
+def _explore(ws, steps) -> None:
+    if not any(label in SUMMARY_STEPS for label, _ in steps) and not (ws.path / "summary" / "manifest.json").exists():
+        return  # a Portal-only job has nothing to explore
+    try:
+        from stackvitals.core.explore import write_explore
+        write_explore(ws.path, ws.repo)
+    except Exception as exc:  # noqa: BLE001 - an extra page must never cost the modules' data
+        ws.notes.append(f"Explore page skipped ({exc}).")
+
+
+def run_job(env: dict, steps: list[tuple[str, object]], now: datetime | None = None, message: str | None = None,
+            catch: bool = True, prepare=None) -> dict:
+    """Open the data branch once, run every step on it, keep house, commit once, then run the hooks. Returns the
+    outcome (pushed, unchanged), each step's result, the errors of steps that failed, and the hooks' notes. `prepare`
+    runs first on each fresh checkout (the repo's settings, shared by every step)."""
+    ws = Workspace(env, now)
+    try:
+        for attempt in range(RETRIES):
+            if attempt:
+                # Two runs collided; a random, growing wait keeps them from colliding again in step.
+                from stackvitals.core.bucket import backoff
+                time.sleep(backoff(attempt))
+            ws.open(attempt)
+            if prepare is not None:
+                try:
+                    prepare(ws)
+                except Exception as exc:  # noqa: BLE001 - the steps still run, on the defaults
+                    ws.notes.append(f"Settings were not read ({exc}); the defaults were used.")
+            try:
+                from stackvitals.core.webapp import write_webapp
+                write_webapp(ws.path / "docs")  # the app at the site's front door, before the pages that link to it
+            except Exception as exc:  # noqa: BLE001 - the app's files must never cost the modules' data
+                ws.notes.append(f"App files skipped ({exc}).")
+            _explore(ws, steps)  # before the modules, so every page they write links to it from the first run
+            results, errors = {}, {}
+            ws.results = results
+            for label, step in steps:
+                if not catch:
+                    results[label] = step(ws)
+                    continue
+                try:
+                    results[label] = step(ws)
+                except Exception as exc:  # noqa: BLE001
+                    # One step's trouble must not lose the others' work; the runner reports it.
+                    errors[label] = str(exc)
+            _explore(ws, steps)  # and after, so its own header lists every page the modules wrote
+            try:
+                from stackvitals.core.appdata import write_app_data
+                write_app_data(ws)  # what the app reads: what ran, settings, decisions, the tables beside the pages
+            except Exception as exc:  # noqa: BLE001 - the app's files must never cost the modules' data
+                ws.notes.append(f"App files skipped ({exc}).")
+            house = housekeeping(ws)
+            try:
+                from stackvitals.core.health import write_health
+                write_health(ws, results, errors, house)  # the app's Data health page
+            except Exception as exc:  # noqa: BLE001 - an extra page must never cost the modules' data
+                ws.notes.append(f"Data health skipped ({exc}).")
+            names = ", ".join(label for label, _ in steps)
+            outcome = ws.commit(message or f"stackvitals: {names} {ws.now:%Y-%m-%d %H:%M} UTC")
+            if outcome != "rejected":
+                break
+        else:
+            raise GitError("the data branch kept changing under us; the next run will catch up")
+        if (env.get("STACKVITALS_SQUASH") or "").strip().lower() == "true" and house["commits"] >= SQUASH_EVERY:
+            # Opt-in: the files stay byte for byte, only the git history behind them becomes one commit.
+            store = HistoryStore(ws.path)
+            store.save_meta({**store.meta(), "commits": 0})
+            house["squashed"] = ws.branch.squash(f"stackvitals: history squashed {ws.now:%Y-%m-%d}") == "pushed"
+        ws.run_hooks()
+        if (env.get("STACKVITALS_STORAGE") or "git") != "git":
+            ws.notes.append("History is kept in the bucket: stackvitals ui and sql, Explore, the MCP server, the Portal's org "
+                            "view and quarantine in your CI read the stackvitals-data branch only, so they don't see it yet."
+                            + ("" if env.get("STACKVITALS_PAGES_DIR") else " No branch publishes the app either: set pages to "
+                               "deploy or artifact."))
+        # Pages from the Action (opt-in): the published folder goes to the deploy steps when this job changed it.
+        pages = bool(env.get("STACKVITALS_PAGES_DIR")) and outcome == "pushed" and (ws.path / "docs").is_dir()
+        if pages:
+            out = Path(env["STACKVITALS_PAGES_DIR"])
+            shutil.copytree(ws.path / "docs", out, dirs_exist_ok=True)
+            if env.get("STACKVITALS_PAGES_MODE") == "artifact":
+                # A download for people who can read the repo, so Explore gets the tables a private repo's Pages leave out.
+                if (ws.path / "summary").is_dir() and not (out / "summary").exists():
+                    shutil.copytree(ws.path / "summary", out / "summary")
+                # The app reads its files over HTTP; bound to this machine so nobody else on the network can open it.
+                (out / "OPEN-ME.txt").write_text(
+                    "Open the StackVitals app from this folder: run `python -m http.server 8000 --bind 127.0.0.1` here,\n"
+                    "then visit http://127.0.0.1:8000/ in a browser. Opening index.html directly doesn't work: browsers block\n"
+                    "its data files.\n", encoding="utf-8")
+        return {"outcome": outcome, "results": results, "errors": errors, "notes": ws.notes, "housekeeping": house, "pages": pages}
+    finally:
+        ws.close()

stackvitals/deps/__init__.py

@@ -0,0 +1 @@
+"""Dependency Steward: should we add, keep, upgrade or replace a package? Evidence over time, never a "safe" stamp."""