stackvitals 0.1.0__py3-none-any.whl

stackvitals/portal/cli.py

@@ -0,0 +1,172 @@
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+
+from stackvitals.ci.api import ActionsAPI
+from stackvitals.ci.cli import ACTION_REF, home, token
+from stackvitals.flow.cli import local_gql as _gql
+from stackvitals.portal.catalog import build_catalog
+from stackvitals.portal.github import NA, read, read_file
+from stackvitals.portal.inventory import list_repos
+
+WORKFLOW = """name: StackVitals Portal
+on:
+  schedule:
+    - cron: "41 5 * * *"   # once a day
+  workflow_dispatch:
+    inputs:
+      request:
+        description: "A request from the StackVitals app, like a golden path (leave empty for a normal run)"
+        required: false
+        default: ""
+  issues:
+    types: [opened]          # golden path requests from the app, run at once
+  issue_comment:
+    types: [created]         # "/stackvitals approve" on a golden path that needs an approval
+permissions:
+  contents: write          # keeps the catalog, its history and the pages in this repo's stackvitals-data branch
+  issues: write            # one tracking issue per campaign, and answers to requests, in this repo only
+concurrency:
+  group: stackvitals-portal
+  cancel-in-progress: false
+jobs:
+  portal:
+    # Request issues start a run only when someone with access to this repo opened one with a StackVitals block.
+    if: >-
+      (github.event_name != 'issues' ||
+       (contains(github.event.issue.body, '```stackvitals') &&
+        contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.issue.author_association))) &&
+      (github.event_name != 'issue_comment' ||
+       (startsWith(github.event.comment.body, '/stackvitals approve') &&
+        contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)))
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      # Private repos: create an org-owned read-only GitHub App (see docs/modules.md), store its client ID and key, then switch on.
+      # - uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3
+      #   id: app
+      #   with:
+      #     client-id: ${{{{ vars.PORTAL_CLIENT_ID }}}}
+      #     private-key: ${{{{ secrets.PORTAL_PRIVATE_KEY }}}}
+      #     owner: ${{{{ github.repository_owner }}}}
+      - uses: {ref}
+        with:
+          modules: portal
+          # portal-token: ${{{{ steps.app.outputs.token }}}}
+"""
+
+
+def _scorecard_client():
+    import httpx
+    return httpx.Client(timeout=20)
+
+
+def app_link(org: str, writes: bool = False) -> str:
+    """GitHub's "register an App" form for the org, filled in: read-only permissions Portal needs, no webhook, private;
+    with `writes`, also what required checks and golden paths need (checks, contents, pull requests, administration)."""
+    from urllib.parse import urlencode
+    params = {"name": f"{org} portal {'' if writes else 'reader'}".strip()[:34],
+              "description": "StackVitals Portal: the org catalog, owners and scorecards"
+              + ("; required checks and golden paths." if writes else " (read-only)."),
+              "url": f"https://github.com/{org}", "public": "false", "webhook_active": "false",
+              "actions": "read", "contents": "write" if writes else "read", "metadata": "read", "members": "read",
+              "organization_custom_properties": "read"}
+    if writes:
+        params |= {"checks": "write", "pull_requests": "write", "administration": "write", "workflows": "write"}
+    return f"https://github.com/organizations/{org}/settings/apps/new?{urlencode(params)}"
+
+
+def check(api, org: str) -> list[str]:
+    """What this token can and can't read, one line per kind of data, so setup problems show before the first run."""
+    repos = list_repos(api, org, "local")
+    private = [r for r in repos if r["private"]]
+    sample = (private or repos or [None])[0]
+    out = [f"{len(repos)} repos visible ({len(private)} private)"]
+    if sample:
+        found = any(read_file(api, sample["name"], p, sample["default_branch"]) is not NA
+                    for p in (".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"))
+        out.append(f"CODEOWNERS: {'readable' if found else 'none found in ' + sample['name']}")
+        out.append("branch rules: " + ("readable" if read(api, f"/repos/{sample['name']}/rules/branches/{sample['default_branch']}")
+                                       is not NA else "not available"))
+    out.append("teams: " + ("readable" if read(api, f"/orgs/{org}/teams", {"per_page": 1}) is not NA else "not available"))
+    out.append("custom properties: " + ("readable" if read(api, f"/orgs/{org}/properties/values", {"per_page": 1}) is not NA
+                                        else "not available"))
+    return out
+
+
+def main(argv: list[str] | None = None, now: datetime | None = None, make_api=ActionsAPI, tok: str | None = None,
+         make_gql=None) -> int:
+    parser = argparse.ArgumentParser(prog="stackvitals portal", description="Portal: what an org owns, who owns it, and its shape.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    rep = sub.add_parser("report", help="Read every repo of an org you can see and show owners with evidence")
+    rep.add_argument("org", help="org or user name")
+    rep.add_argument("--json", action="store_true")
+    rep.add_argument("--budget", type=int, default=3000, help="most API requests to spend; the next run continues")
+    rep.add_argument("--no-scorecard", dest="scorecard", action="store_false", help="skip OpenSSF Scorecard results")
+    chk = sub.add_parser("check", help="Say what your token can read in an org before the first run")
+    chk.add_argument("org", help="org or user name")
+    ini = sub.add_parser("init", help="Print the workflow for the org's private portal repo")
+    ini.add_argument("--ref", default=ACTION_REF)
+    lnk = sub.add_parser("app-link", help="Print a link that opens GitHub's App form with Portal's read-only permissions filled in")
+    lnk.add_argument("org", help="org name")
+    lnk.add_argument("--writes", action="store_true", help="also the write permissions required checks and golden paths need")
+    args = parser.parse_args(argv)
+    if args.cmd == "init":
+        print(WORKFLOW.format(ref=args.ref), end="")
+        return 0
+    if args.cmd == "app-link":
+        print(app_link(args.org, args.writes))
+        print("Then: create the App, install it on the org's repos, save its client ID as the variable PORTAL_CLIENT_ID and a "
+              "private key as the secret PORTAL_PRIVATE_KEY, and switch on the token step in the portal workflow.")
+        return 0
+    tok = tok or token()
+    if not tok:
+        print("A GitHub token is needed. Set GITHUB_TOKEN, or run `gh auth login`.", file=sys.stderr)
+        return 1
+    if args.cmd == "check":
+        for line in check(make_api(tok, f"{args.org}/portal", max_requests=50), args.org):
+            print(line)
+        return 0
+    now = now or datetime.now(timezone.utc)
+    path = home() / "portal" / f"{args.org}.json"
+    try:
+        previous = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        previous = None
+    from stackvitals.ci import bench as ci_bench
+    from stackvitals.flow import peers as flow_peers
+    from stackvitals.portal.scorecard import rules_or_default, score_catalog
+    make_gql = make_gql or _gql
+    catalog = build_catalog(make_api(tok, f"{args.org}/portal", max_requests=args.budget), args.org, "local", now, previous,
+                            scorecard_client=_scorecard_client() if args.scorecard else None, gql=make_gql(tok))
+    rules, exemptions, _ = rules_or_default(None)
+    score_catalog(catalog, rules, exemptions, now, {"ci": ci_bench.load(tok, home() / "bench"),
+                                                    "flow": flow_peers.load(tok, home() / "bench")})
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(catalog, indent=1), encoding="utf-8")
+    if args.json:
+        print(json.dumps(catalog, indent=1))
+        return 0
+    active = [r for r in catalog["repos"] if not r.get("archived") and not r.get("fork")]
+    judged = [r for r in active if r["name"].split("/")[-1].lower() != ".github"]
+    counts = {s: sum(1 for r in judged if (r.get("owners") or {}).get("status") == s) for s in ("valid", "weak", "none")}
+    print(f"{args.org}: {len(catalog['repos'])} repos, {len(active)} active (archived repos and forks are listed, not checked). "
+          f"Owners: {counts['valid']} valid, {counts['weak']} weak, {counts['none']} none.")
+    from stackvitals.portal.pages import catalog_entities
+    entities, problems, files = catalog_entities(judged)
+    if files:
+        print(f"Catalog: {len(entities)} entities from {files} repos' catalog-info.yaml, {len(problems)} problems in them.")
+    for r in active:
+        o = r.get("owners") or {}
+        if r["name"].split("/")[-1].lower() == ".github":
+            print(f"  {r['name']:40} {'-':12} {'-':8} the org's shared settings repo: not judged")
+            continue
+        why = "; ".join(o.get("reasons") or []) + (
+            f" (suggested from {o.get('suggested_from') or 'recent commits'}: {', '.join(o['suggested'])})" if o.get("suggested") else "")
+        # A scored repo below bronze says so; "-" is left for repos not scored at all.
+        level = ((r.get("score") or {}).get("level") or "below bronze") if r.get("score") else "-"
+        print(f"  {r['name']:40} {level:12} {o.get('status') or 'not checked yet':8} {why}")
+    if not catalog["complete"]:
+        print("\n(Not every repo was checked yet; run the same command again to continue.)")
+    return 0

stackvitals/portal/descriptor.py

@@ -0,0 +1,105 @@
+"""A repo's catalog-info.yaml, Backstage's descriptor format (Port and Cortex read it too): what the repo says it is, who
+owns it, which system it belongs to and what it depends on. Read with safe YAML only; problems are listed, never fatal."""
+import re
+
+import yaml
+
+FILE = "catalog-info.yaml"
+MAX_BYTES = 256_000
+MAX_DOCS = 50
+KINDS = {k.lower(): k for k in ("Component", "API", "Resource", "System", "Domain", "Group", "User", "Location", "Template")}
+# The spec fields Backstage itself requires for these kinds.
+NEEDS = {"Component": ("type", "lifecycle", "owner"), "API": ("type", "lifecycle", "owner"), "Resource": ("type", "owner"),
+         "System": ("owner",), "Domain": ("owner",)}
+REF = re.compile(r"^(?:([A-Za-z][\w-]*):)?(?:([\w.-]+)/)?([\w.-]+)$")
+
+
+def _text(value, cap: int = 200) -> str | None:
+    # Scalars only (str() of a container could expand an alias bomb), and no huge numbers.
+    if isinstance(value, bool) or not isinstance(value, (str, int, float)) or isinstance(value, int) and value.bit_length() > 256:
+        return None
+    return " ".join(str(value).split())[:cap] or None
+
+
+def _names(value) -> list[str]:
+    return [t for x in value[:50] if (t := _text(x))] if isinstance(value, list) else []
+
+
+def ref(value: str | None, default_kind: str) -> tuple[str, str, str] | None:
+    """Backstage's entity reference `[kind:][namespace/]name`, lower-cased, or None."""
+    found = REF.match(str(value or "").strip())
+    if not found:
+        return None
+    kind, namespace, name = found.groups()
+    return (kind or default_kind).lower(), (namespace or "default").lower(), name.lower()
+
+
+def _entity(doc: dict) -> dict:
+    meta = doc.get("metadata") if isinstance(doc.get("metadata"), dict) else {}
+    spec = doc.get("spec") if isinstance(doc.get("spec"), dict) else {}
+    links = [{"url": str(x["url"])[:300], "title": _text(x.get("title"), 80) or str(x["url"])[:80]}
+             for x in (meta.get("links") if isinstance(meta.get("links"), list) else [])[:5]
+             if isinstance(x, dict) and re.match(r"https?://", str(x.get("url") or ""))]
+    return {"kind": KINDS[str(doc["kind"]).lower()], "name": _text(meta.get("name"), 100), "title": _text(meta.get("title"), 100),
+            "description": _text(meta.get("description")), "type": _text(spec.get("type"), 60),
+            "lifecycle": _text(spec.get("lifecycle"), 60), "owner": _text(spec.get("owner"), 120),
+            "system": _text(spec.get("system"), 120), "domain": _text(spec.get("domain"), 120),
+            "part_of": _text(spec.get("subcomponentOf"), 120), "depends_on": _names(spec.get("dependsOn")),
+            "provides_apis": _names(spec.get("providesApis")), "consumes_apis": _names(spec.get("consumesApis")),
+            "tags": _names(meta.get("tags"))[:10], "links": links}
+
+
+def parse(text: str) -> tuple[list[dict], list[str]]:
+    """The entities a catalog-info.yaml declares and the problems in it, in plain words."""
+    if len(text.encode("utf-8", "replace")) > MAX_BYTES:
+        return [], [f"{FILE} is over {MAX_BYTES // 1000} KB; not read"]
+    try:
+        docs = [d for d in yaml.safe_load_all(text)][:MAX_DOCS + 1]
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        where = f" (line {mark.line + 1})" if mark is not None else ""
+        return [], [f"not valid YAML{where}: {getattr(exc, 'problem', None) or type(exc).__name__}"]
+    except Exception as exc:  # deep nesting, impossible dates, numbers too long to convert: the file is the problem
+        return [], [f"not valid YAML: {type(exc).__name__}"]
+    docs = [d for d in docs if d is not None]
+    if not docs:
+        return [], [f"{FILE} is empty"]
+    entities, problems = [], []
+    if len(docs) > MAX_DOCS:
+        problems.append(f"only the first {MAX_DOCS} documents were read")
+    for i, doc in enumerate(docs[:MAX_DOCS], 1):
+        if not isinstance(doc, dict):
+            problems.append(f"document {i} is not a mapping")
+            continue
+        kind = doc.get("kind")
+        if not isinstance(kind, str) or kind.lower() not in KINDS:
+            problems.append(f"document {i}: {_text(kind, 40) or 'no kind'} is not a Backstage kind")
+            continue
+        try:
+            e = _entity(doc)
+        except Exception as exc:  # one odd document never hides the others
+            problems.append(f"document {i}: could not be read ({type(exc).__name__})")
+            continue
+        if not e["name"]:
+            problems.append(f"document {i}: no metadata.name")
+            continue
+        missing = [f for f in NEEDS.get(e["kind"], ()) if not e[f]]
+        if missing:
+            problems.append(f"{e['kind']} {e['name']}: no {', '.join(missing)}")
+        entities.append(e)
+    return entities, problems
+
+
+def owner_check(owner: str | None, codeowners: list[str]) -> tuple[str, str]:
+    """pass when the catalog's owner is named in CODEOWNERS (a team as @org/team, a person as @login), fail when not."""
+    if not owner:
+        return "fail", f"{FILE} names no owner"
+    found = ref(owner, "group")
+    named = {}
+    for o in codeowners:
+        if o.startswith("@"):
+            named.setdefault(o[1:].split("/")[-1].lower(), o)
+    if found and found[2] in named:
+        return "pass", f"{found[2]} is {named[found[2]]} in CODEOWNERS"
+    listed = [o for o in codeowners if o.startswith("@")]
+    return "fail", f"{FILE} names {owner}; CODEOWNERS names {', '.join(listed) or 'nobody'}"

stackvitals/portal/export.py

@@ -0,0 +1,43 @@
+"""Backstage entities for the repos that don't describe themselves: one file of Components (portal/entities.yaml on the
+data branch) Backstage can register as a single location, each with its owner from CODEOWNERS, the StackVitals level as
+an annotation and a link back to the portal. Repos with their own catalog-info.yaml are left to it."""
+import re
+
+import yaml
+
+LIFECYCLE = "production"
+
+
+def _name(repo: str) -> str:
+    # Backstage names: letters, digits and [-_.], at most 63 characters, starting and ending alphanumeric.
+    name = re.sub(r"[^A-Za-z0-9._-]", "-", repo.split("/")[-1])[:63].strip("-_.")
+    return name or "repo"
+
+
+def _owner(owners: dict | None) -> str:
+    first = next(iter((owners or {}).get("owners") or []), "")
+    if first.startswith("@") and "/" in first:
+        return "group:" + first.split("/", 1)[1]
+    if first.startswith("@"):
+        return "user:" + first[1:]
+    return "unknown"
+
+
+def entity(repo: dict, portal_url: str | None) -> dict:
+    level = (repo.get("score") or {}).get("level")
+    tags = sorted({t.lower() for t in (repo.get("topics") or [])} | ({repo["language"].lower()} if repo.get("language") else set()))
+    tags = [re.sub(r"[^a-z0-9+#-]", "-", t)[:63] for t in tags]
+    meta = {"name": _name(repo["name"]), "description": repo.get("description") or "",
+            "annotations": {"github.com/project-slug": repo["name"], "stackvitals.dev/level": level or "below bronze",
+                            "stackvitals.dev/owners": (repo.get("owners") or {}).get("status") or "unknown"},
+            "tags": tags}
+    if portal_url:
+        meta["links"] = [{"url": f"{portal_url.rstrip('/')}/#/portal?tab=repos", "title": "StackVitals portal"}]
+    return {"apiVersion": "backstage.io/v1alpha1", "kind": "Component", "metadata": meta,
+            "spec": {"type": "service", "lifecycle": LIFECYCLE, "owner": _owner(repo.get("owners"))}}
+
+
+def entities_yaml(repos: list[dict], portal_url: str | None) -> str:
+    live = [r for r in repos if not r.get("archived") and not r.get("fork") and not (r.get("descriptor") or {}).get("present")
+            and r["name"].split("/")[-1].lower() != ".github"]
+    return yaml.safe_dump_all([entity(r, portal_url) for r in live], sort_keys=False, allow_unicode=True)

stackvitals/portal/github.py

@@ -0,0 +1,48 @@
+"""Every Portal read goes through here: a refusal or a missing item is "not available", never a failure, because GitHub
+keeps changing what a token may read (stargazer lists in July 2026, the SBOM export endpoint ending 2026-11-13)."""
+import httpx
+
+from stackvitals.ci.api import API, APIError, OutOfBudget
+
+REFUSED = ("HTTP 401", "HTTP 403", "HTTP 404", "HTTP 409", "HTTP 410", "HTTP 451")
+
+
+class _NotAvailable:
+    def __repr__(self) -> str:
+        return "not available"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+NA = _NotAvailable()
+
+
+def read(api, path: str, params: dict | None = None):
+    try:
+        return api._get(path, params)
+    except APIError as exc:
+        if any(code in str(exc) for code in REFUSED):
+            return NA
+        raise
+
+
+def read_file(api, repo: str, path: str, ref: str | None = None):
+    try:
+        return api.file(path, ref, repo=repo).decode("utf-8", "replace")
+    except APIError as exc:
+        if any(code in str(exc) for code in REFUSED):
+            return NA
+        raise
+
+
+def status(api, path: str) -> int | None:
+    """Only the HTTP status (membership checks answer 204 or 404 with no body)."""
+    with api._lock:
+        if api.max_requests is not None and api.requests >= api.max_requests:
+            raise OutOfBudget(f"stopped after {api.requests} requests (budget)")
+        api.requests += 1
+    try:
+        return api.client.get(f"{API}{path}", headers=api.headers).status_code
+    except httpx.TransportError:
+        return None

stackvitals/portal/golden.py

@@ -0,0 +1,95 @@
+"""Golden paths (opt-in): the portal repo's portal.toml names templates people can run from the app or a request, and
+the Portal's org App carries them out: a new repo from a template repo, or a pull request that adds a folder of the
+portal repo's files (a standard CI workflow, a CODEOWNERS, a catalog-info.yaml) to an existing repo. Only people with
+write access to the portal repo can run one, each run is recorded as a decision, and nothing runs without the App."""
+import base64
+import re
+import tomllib
+
+from stackvitals.ci.api import APIError
+
+NAME = re.compile(r"[A-Za-z0-9._-]{1,100}")
+KINDS = ("repo", "files")
+
+
+class GoldenError(Exception):
+    """A golden path that can't run as asked; the message says why."""
+
+
+def load_paths(text: str | None) -> dict[str, dict]:
+    """Each [[golden_path]]: id, title, kind ("repo" with a template, or "files" with a folder of the portal repo)."""
+    doc = tomllib.loads(text or "")
+    out = {}
+    for g in doc.get("golden_path") or []:
+        if not isinstance(g, dict) or not NAME.fullmatch(str(g.get("id") or "")) or g.get("kind") not in KINDS:
+            raise GoldenError("Each [[golden_path]] needs an id and a kind (repo or files).")
+        if g["kind"] == "repo" and not re.fullmatch(r"[\w.-]+/[\w.-]+", str(g.get("template") or "")):
+            raise GoldenError(f"Golden path {g['id']} needs template = \"owner/template-repo\".")
+        if g["kind"] == "files" and not str(g.get("folder") or "").strip("/"):
+            raise GoldenError(f"Golden path {g['id']} needs folder = \"golden/{g['id']}\" in the portal repo.")
+        if g.get("approvals", 0) not in (0, 1):
+            raise GoldenError(f"Golden path {g['id']}: approvals is 0 or 1 (someone other than the requester approves).")
+        out[g["id"]] = {"id": g["id"], "title": str(g.get("title") or g["id"]), "kind": g["kind"],
+                        "template": g.get("template"), "folder": str(g.get("folder") or "").strip("/"),
+                        "private": bool(g.get("private", True)), "description": str(g.get("description") or ""),
+                        "approvals": int(g.get("approvals", 0))}
+    return out
+
+
+def _new_repo(app, org: str, path: dict, inputs: dict) -> tuple[str, str]:
+    name = str(inputs.get("name") or "")
+    if not NAME.fullmatch(name) or name.startswith("."):
+        raise GoldenError("The new repo's name may hold letters, digits, dots, dashes and underscores only.")
+    made = app.send("POST", f"/repos/{path['template']}/generate",
+                    {"owner": org, "name": name, "description": str(inputs.get("description") or "")[:300],
+                     "private": path["private"]})
+    url = made.get("html_url") or f"https://github.com/{org}/{name}"
+    return f"Created {org}/{name} from {path['template']} ({'private' if path['private'] else 'public'}).", url
+
+
+def _files_pr(app, portal_api, portal_repo: str, org: str, path: dict, inputs: dict, requester: str) -> tuple[str, str]:
+    target = str(inputs.get("repo") or "")
+    owner, _, name = target.partition("/")
+    if owner.lower() != org.lower() or not NAME.fullmatch(name):
+        raise GoldenError(f"Golden paths only change repos in {org}; say which one as repo = \"{org}/<name>\".")
+    # Write access to the portal repo isn't write access to every repo: the requester must be able to push to the target.
+    try:
+        level = app._get(f"/repos/{target}/collaborators/{requester}/permission").get("permission")
+    except APIError:
+        level = None
+    if level not in ("admin", "maintain", "write"):
+        raise GoldenError(f"{requester} can't write to {target}, so this golden path won't open a pull request there.")
+    prefix = path["folder"] + "/"
+    tree = portal_api._get(f"/repos/{portal_repo}/git/trees/HEAD", {"recursive": "1"}).get("tree") or []
+    files = [t["path"] for t in tree if t.get("type") == "blob" and t["path"].startswith(prefix)]
+    if not files:
+        raise GoldenError(f"The portal repo has no files under {prefix}.")
+    base = app._get(f"/repos/{target}").get("default_branch") or "main"
+    sha = app._get(f"/repos/{target}/git/ref/heads/{base}")["object"]["sha"]
+    branch = f"stackvitals/golden-{path['id']}"
+    try:
+        app.send("POST", f"/repos/{target}/git/refs", {"ref": f"refs/heads/{branch}", "sha": sha})
+    except APIError as exc:
+        if "HTTP 422" not in str(exc):  # the branch is there from an earlier try: carry on with it
+            raise
+    for f in files:
+        content, dest = portal_api.file(f, None, repo=portal_repo), f[len(prefix):]
+        # A file that already exists (a CODEOWNERS being replaced) is updated, which needs its current sha.
+        try:
+            current = app._get(f"/repos/{target}/contents/{dest}", {"ref": branch}).get("sha")
+        except APIError:
+            current = None
+        app.send("PUT", f"/repos/{target}/contents/{dest}",
+                 {"message": f"Add {path['title']} (StackVitals golden path)", "branch": branch,
+                  "content": base64.b64encode(content).decode(), **({"sha": current} if current else {})})
+    pr = app.send("POST", f"/repos/{target}/pulls",
+                  {"title": f"Add {path['title']}", "head": branch, "base": base,
+                   "body": f"Golden path `{path['id']}` from {portal_repo}: {len(files)} file(s). Review and merge as usual."})
+    return f"Opened a pull request in {target} adding {len(files)} file(s).", pr.get("html_url") or ""
+
+
+def run(app, portal_api, portal_repo: str, org: str, path: dict, inputs: dict, requester: str) -> tuple[str, str]:
+    """Carries out one golden path for `requester`; returns what happened and a link to it."""
+    if path["kind"] == "repo":
+        return _new_repo(app, org, path, inputs)
+    return _files_pr(app, portal_api, portal_repo, org, path, inputs, requester)

stackvitals/portal/history.py

@@ -0,0 +1,30 @@
+"""Since when: the daily history lines say how long a repo has had its owner status and level, which no one-off look can."""
+import json
+from pathlib import Path
+
+
+def since(folder: Path, repos: list[dict], today: str, keep: int = 400) -> dict[str, dict[str, str]]:
+    """For each repo, the first day of the unbroken run of days with today's owner status and level (today if new)."""
+    days = []
+    for path in sorted(Path(folder).glob("*.json"))[-keep:]:
+        if path.stem >= today:
+            continue
+        try:
+            rows = json.loads(path.read_text(encoding="utf-8")).get("repos") or []
+        except (OSError, ValueError):
+            continue
+        days.append((path.stem, {r.get("name"): r for r in rows if isinstance(r, dict)}))
+    out = {}
+    for r in repos:
+        now = {"owners": (r.get("owners") or {}).get("status"), "level": (r.get("score") or {}).get("level")}
+        found = {}
+        for key, value in now.items():
+            start = today
+            for day, rows in reversed(days):
+                row = rows.get(r["name"])
+                if not row or row.get(key) != value:
+                    break
+                start = day
+            found[key] = start
+        out[r["name"]] = found
+    return out