Skip to content

teng-lin/notebooklm-py

notebooklm

Verified

Install, authenticate, troubleshoot, and operate Gemini Notebook through the notebooklm-py CLI or typed async Python API. Use for notebook and source management, grounded chat and research, and artifact generation or download when the user mentions Gemini Notebook, notebooklm-py, the notebooklm CLI, or its Python API. Do not use for the generic Gemini API or unrelated content creation.

FileKindSize
SKILL.mdskill md16.0 KB
examples/bulk-import.pyscript3.4 KB
examples/chat.pyscript6.9 KB
examples/notes.pyscript9.8 KB
examples/quickstart.pyscript2.3 KB
examples/refresh_browser_cookies.pyscript2.9 KB
examples/research-to-podcast.pyscript3.2 KB
examples/video.pyscript5.9 KB
scripts/__init__.pyscript73 B
scripts/_ci_e2e_notebooks.pyscript19.0 KB
scripts/_ci_progress.pyscript2.5 KB
scripts/_ci_rpc_progress.pyscript7.5 KB
scripts/_live_auth_scenarios/__init__.pyscript2.6 KB
scripts/_live_auth_scenarios/_contract.pyscript1.9 KB
scripts/_live_auth_scenarios/browser_refresh.pyscript3.1 KB
scripts/_live_auth_scenarios/crash_safe_writer.pyscript1.9 KB
scripts/_live_auth_scenarios/master_token_recovery.pyscript3.3 KB
scripts/_live_auth_scenarios/mcp_recovery.pyscript3.0 KB
scripts/_live_auth_scenarios/rest_recovery.pyscript5.9 KB
scripts/_live_auth_scenarios/sibling_concurrent_reload.pyscript3.9 KB
scripts/_live_auth_scenarios/storage_reload.pyscript2.9 KB
scripts/_onetime_rescrub_cookies.pyscript6.6 KB
scripts/_onetime_retarget_cassette_hosts.pyscript8.5 KB
scripts/_strip_audit_refs.pyscript15.9 KB
scripts/_tracked_files.pyscript872 B
scripts/aggregate_ci_e2e_outcomes.pyscript10.8 KB
scripts/android_grpc_canary.pyscript26.6 KB
scripts/api-compat-allowlist.jsonconfig163 B
scripts/audit_auth_import_graph.pyscript7.5 KB
scripts/audit_auth_patch_sites.pyscript83.6 KB
scripts/audit_auth_shared_mutations.pyscript41.7 KB
scripts/audit_backend_coupling.pyscript32.8 KB
scripts/audit_public_api_compat.pyscript47.4 KB
scripts/audit_test_suite.pyscript10.7 KB
scripts/capture_mobile_grpc.jsscript5.1 KB
scripts/capture_rpc_registry.pyscript44.5 KB
scripts/check_action_pinning.pyscript6.7 KB
scripts/check_auth_behavior_scenario_policy.pyscript37.1 KB
scripts/check_auth_coverage_delta.pyscript23.2 KB
scripts/check_auth_lifecycle_cleanup_policy.pyscript11.7 KB
scripts/check_base_wheel.pyscript6.3 KB
scripts/check_ci_install_parity.pyscript8.8 KB
scripts/check_claude_md_freshness.pyscript8.0 KB
scripts/check_coverage_thresholds.pyscript8.4 KB
scripts/check_deprecation_targets.pyscript33.1 KB
scripts/check_docs_module_refs.pyscript14.4 KB
scripts/check_rpc_health.pyscript112.0 KB
scripts/check_workflow_permissions.pyscript5.3 KB
scripts/check_workflow_secret_gates.pyscript40.4 KB
scripts/decode_mobile_grpc.pyscript7.2 KB
scripts/diagnose_get_notebook.pyscript9.1 KB
scripts/extract_blutter_grpc_signatures.pyscript7.6 KB
scripts/live_auth_matrix.pyscript40.2 KB
scripts/manage_ci_e2e_notebooks.pyscript67.4 KB
scripts/materialize_ci_auth.pyscript8.0 KB
scripts/mcp_live_smoke.pyexecutablescript224 B
scripts/parse_pbenums.pyscript8.6 KB
scripts/parse_pbschema.pyscript11.8 KB
scripts/regen_baselines.pyscript2.7 KB
scripts/regenerate_android_protos.pyscript16.3 KB
scripts/rescrub-cassettes.pyscript13.3 KB
scripts/scrub_rpc_har.pyscript9.4 KB
scripts/select_ci_account.pyscript4.8 KB
scripts/stress_fault_server.pyscript20.6 KB
scripts/test_taxonomy_inventory.pyscript16.1 KB
scripts/verify_ci_artifacts.pyscript35.3 KB

scripts/check_auth_coverage_delta.py

View on GitHub
#!/usr/bin/env python3
"""Compare merge-base/head auth coverage for every patch-migration-affected module."""

from __future__ import annotations

import argparse
import json
import re
import subprocess
import sys
import tempfile
from datetime import date, datetime, timezone
from pathlib import Path
from typing import Any

REPO_ROOT = Path(__file__).resolve().parent.parent
SCENARIO_POLICY = Path("tests/fixtures/policies/auth_behavior_scenarios.json")
LIFECYCLE_POLICY = Path("tests/fixtures/policies/auth_lifecycle_cleanup.json")
ALLOWANCE_POLICY = Path("tests/fixtures/policies/auth_coverage_allowances.json")
IN_SCOPE_PREFIXES = (
    "src/notebooklm/_auth/",
    "src/notebooklm/_browser/",
    "src/notebooklm/auth.py",
    "tests/",
    "scripts/audit_auth_",
    "scripts/check_auth_",
    ".github/workflows/test.yml",
    "docs/adr/",
    "docs/development.md",
)


class CoverageDeltaError(RuntimeError):
    def __init__(self, message: str, *, losses: list[dict[str, Any]] | None = None) -> None:
        super().__init__(message)
        self.losses = losses


def _load(path: Path) -> dict[str, Any]:
    value = json.loads(path.read_text(encoding="utf-8"))
    if not isinstance(value, dict):
        raise CoverageDeltaError(f"{path}: expected an object")
    return value


def _git(*args: str, cwd: Path = REPO_ROOT) -> str:
    result = subprocess.run(["git", *args], cwd=cwd, text=True, capture_output=True)
    if result.returncode != 0:
        raise CoverageDeltaError(result.stderr.strip() or f"git {' '.join(args)} failed")
    return result.stdout


def changed_paths(base: str) -> set[str]:
    return set(filter(None, _git("diff", "--name-only", base, "--").splitlines()))


def _policy_at(workspace: Path, path: Path) -> dict[str, Any]:
    full = workspace / path
    if not full.is_file():
        name = (
            "allowances"
            if "allowance" in path.name
            else "operations"
            if "lifecycle" in path.name
            else "scenarios"
        )
        return {"version": 1, name: []}
    return _load(full)


def _policy_at_revision(base: str, path: Path) -> dict[str, Any]:
    result = subprocess.run(
        ["git", "show", f"{base}:{path.as_posix()}"],
        cwd=REPO_ROOT,
        text=True,
        capture_output=True,
    )
    if result.returncode != 0:
        name = (
            "allowances"
            if "allowance" in path.name
            else "operations"
            if "lifecycle" in path.name
            else "scenarios"
        )
        return {"version": 1, name: []}
    return json.loads(result.stdout)


def validate_allowances(
    policy: dict[str, Any],
    *,
    base_sha: str,
    scenario_ids: set[str] | dict[str, set[str]],
    today: date | None = None,
) -> list[dict[str, Any]]:
    if policy.get("version") != 1 or not isinstance(policy.get("allowances"), list):
        raise CoverageDeltaError("allowance policy must be version 1 with an allowances list")
    today = today or datetime.now(timezone.utc).date()
    rows: list[dict[str, Any]] = []
    ids: set[str] = set()
    for row in policy["allowances"]:
        required = {
            "id",
            "path",
            "kind",
            "base_coordinate",
            "head_coordinate",
            "disposition",
            "scenario_id",
            "rationale",
            "owner",
            "valid_for_base_sha",
            "authored_on",
            "expires_on",
        }
        if set(row) != required:
            raise CoverageDeltaError(f"allowance row has wrong fields: {set(row) ^ required}")
        if row["id"] in ids:
            raise CoverageDeltaError(f"duplicate allowance id: {row['id']}")
        ids.add(row["id"])
        if row["valid_for_base_sha"] != base_sha:
            raise CoverageDeltaError(f"{row['id']}: valid_for_base_sha is not the merge base")
        authored = date.fromisoformat(row["authored_on"])
        expires = date.fromisoformat(row["expires_on"])
        if authored > today:
            raise CoverageDeltaError(f"{row['id']}: authored_on is in the future")
        if (expires - authored).days > 14 or expires < authored:
            raise CoverageDeltaError(f"{row['id']}: expiry must be within 14 days")
        if expires < today:
            raise CoverageDeltaError(f"{row['id']}: allowance expired")
        if row["scenario_id"] not in scenario_ids:
            raise CoverageDeltaError(f"{row['id']}: scenario link does not exist")
        if isinstance(scenario_ids, dict) and row["path"] not in scenario_ids[row["scenario_id"]]:
            raise CoverageDeltaError(f"{row['id']}: scenario does not cover the allowance path")
        if row["kind"] not in {"statement", "branch"}:
            raise CoverageDeltaError(f"{row['id']}: invalid coordinate kind")
        if row["disposition"] not in {"mapped", "removed"}:
            raise CoverageDeltaError(f"{row['id']}: invalid disposition")
        if any(token in str(row["path"]) for token in ("*", "?", "[")):
            raise CoverageDeltaError(f"{row['id']}: wildcard paths are forbidden")
        if not str(row["path"]).startswith("src/notebooklm/"):
            raise CoverageDeltaError(f"{row['id']}: path is outside production source")
        base_coordinate = row["base_coordinate"]
        head_coordinate = row["head_coordinate"]
        if row["kind"] == "statement":
            valid_base = isinstance(base_coordinate, int) and not isinstance(base_coordinate, bool)
            valid_head = isinstance(head_coordinate, int) and not isinstance(head_coordinate, bool)
        else:
            valid_base = (
                isinstance(base_coordinate, list)
                and len(base_coordinate) == 2
                and all(
                    isinstance(item, int) and not isinstance(item, bool) for item in base_coordinate
                )
            )
            valid_head = (
                isinstance(head_coordinate, list)
                and len(head_coordinate) == 2
                and all(
                    isinstance(item, int) and not isinstance(item, bool) for item in head_coordinate
                )
            )
        if not valid_base:
            raise CoverageDeltaError(f"{row['id']}: invalid base coordinate")
        if row["disposition"] == "mapped" and not valid_head:
            raise CoverageDeltaError(
                f"{row['id']}: mapped allowance needs an exact head coordinate"
            )
        if row["disposition"] == "removed" and head_coordinate is not None:
            raise CoverageDeltaError(f"{row['id']}: removed allowance head coordinate must be null")
        if not str(row["rationale"]).strip() or not str(row["owner"]).strip():
            raise CoverageDeltaError(f"{row['id']}: rationale and owner are required")
        rows.append(row)
    return rows


def _module_path(package: str, module: str) -> str:
    if package == "notebooklm.auth":
        return "src/notebooklm/auth.py"
    return f"src/{package.replace('.', '/')}/{module}.py"


def _collect_projections(workspace: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
    if str(REPO_ROOT) not in sys.path:
        sys.path.insert(0, str(REPO_ROOT))
    from scripts.audit_auth_patch_sites import build_projection, collect_sites
    from scripts.audit_auth_shared_mutations import (
        build_projection as build_shared,
    )
    from scripts.audit_auth_shared_mutations import (
        collect_mutations,
    )

    tests = workspace / "tests"
    projections = [
        build_projection(collect_sites(tests, workspace / "src/notebooklm/_auth")),
        build_projection(
            collect_sites(
                tests,
                workspace / "src/notebooklm/_browser",
                package_dotted="notebooklm._browser",
            )
        ),
        build_projection(
            collect_sites(
                tests,
                workspace / "src/notebooklm/auth.py",
                package_dotted="notebooklm.auth",
            )
        ),
    ]
    shared = build_shared(
        collect_mutations(
            tests,
            {
                "notebooklm._auth": workspace / "src/notebooklm/_auth",
                "notebooklm._browser": workspace / "src/notebooklm/_browser",
            },
        )
    )
    return projections, shared


def _all_joint(projections: list[dict[str, Any]]) -> list[dict[str, Any]]:
    return [row for projection in projections for row in projection.get("joint_sites", [])]


def _changed_policy_rows(
    base_policy: dict[str, Any], head_policy: dict[str, Any], collection: str
) -> list[dict[str, Any]]:
    old = {
        json.dumps(row, sort_keys=True, separators=(",", ":")): row
        for row in base_policy.get(collection, [])
    }
    new = {
        json.dumps(row, sort_keys=True, separators=(",", ":")): row
        for row in head_policy.get(collection, [])
    }
    return [*(old[key] for key in old.keys() - new), *(new[key] for key in new.keys() - old)]


def derive_affected_paths(
    *,
    changed: set[str],
    base_workspace: Path,
    head_workspace: Path,
    base_revision: str,
) -> set[str]:
    affected = {
        path
        for path in changed
        if path.startswith("src/notebooklm/_auth/")
        or path.startswith("src/notebooklm/_browser/")
        or path == "src/notebooklm/auth.py"
    }
    base_projections, base_shared = _collect_projections(base_workspace)
    head_projections, head_shared = _collect_projections(head_workspace)
    old_rows = _all_joint(base_projections)
    new_rows = _all_joint(head_projections)
    identity_fields = (
        "package",
        "module",
        "attribute",
        "idiom",
        "path",
        "owner_qualname",
        "owner_kind",
    )
    old = {tuple(row[field] for field in identity_fields): int(row["count"]) for row in old_rows}
    new = {tuple(row[field] for field in identity_fields): int(row["count"]) for row in new_rows}
    for identity in set(old) | set(new):
        if old.get(identity) != new.get(identity):
            affected.add(_module_path(str(identity[0]), str(identity[1])))
    shared_fields = (
        "package",
        "owner",
        "attribute",
        "idiom",
        "path",
        "owner_qualname",
        "owner_kind",
    )
    old_shared = {
        tuple(row[field] for field in shared_fields): int(row["count"])
        for row in base_shared.get("mutations", [])
    }
    new_shared = {
        tuple(row[field] for field in shared_fields): int(row["count"])
        for row in head_shared.get("mutations", [])
    }
    for identity in set(old_shared) | set(new_shared):
        if old_shared.get(identity) != new_shared.get(identity):
            owner_tail = str(identity[1])[len(str(identity[0])) + 1 :]
            affected.add(_module_path(str(identity[0]), owner_tail.split(".", 1)[0]))
    changed_tests = {path for path in changed if path.startswith("tests/") and path.endswith(".py")}
    for row in (*old_rows, *new_rows):
        if row["path"] in changed_tests:
            affected.add(_module_path(row["package"], row["module"]))
    for projection in (base_shared, head_shared):
        for row in projection.get("mutations", []):
            if row["path"] in changed_tests:
                tail = row["owner"][len(row["package"]) + 1 :].split(".", 1)[0]
                affected.add(_module_path(row["package"], tail))
    if any(
        path.startswith("scripts/audit_auth_")
        or path.startswith("tests/_baselines/")
        or path.startswith("tests/fixtures/baselines/auth_")
        for path in changed
    ):
        for row in (*old_rows, *new_rows):
            affected.add(_module_path(row["package"], row["module"]))
        for projection in (base_shared, head_shared):
            for row in projection.get("mutations", []):
                tail = row["owner"][len(row["package"]) + 1 :].split(".", 1)[0]
                affected.add(_module_path(row["package"], tail))
    policy_collections = (
        (SCENARIO_POLICY, "scenarios"),
        (LIFECYCLE_POLICY, "operations"),
        (ALLOWANCE_POLICY, "allowances"),
    )
    for path, collection in policy_collections:
        base_policy = _policy_at_revision(base_revision, path)
        head_policy = _policy_at(head_workspace, path)
        for row in _changed_policy_rows(base_policy, head_policy, collection):
            affected.update(row.get("affected_paths", []))
            if isinstance(row.get("path"), str):
                affected.add(row["path"])
            if isinstance(row.get("source_path"), str):
                affected.add(row["source_path"])
    return {path for path in affected if path.startswith("src/notebooklm/")}


def _line_map(base_text: str, head_text: str) -> dict[int, int]:
    """Map unchanged lines using Git's zero-context diff hunk boundaries."""
    old = base_text.splitlines()
    new = head_text.splitlines()
    with tempfile.TemporaryDirectory(prefix="auth-coverage-diff-") as temporary:
        root = Path(temporary)
        old_path = root / "base.py"
        new_path = root / "head.py"
        old_path.write_text(base_text, encoding="utf-8")
        new_path.write_text(head_text, encoding="utf-8")
        result = subprocess.run(
            [
                "git",
                "diff",
                "--no-index",
                "--unified=0",
                "--no-color",
                "--",
                str(old_path),
                str(new_path),
            ],
            text=True,
            capture_output=True,
        )
    if result.returncode not in {0, 1}:
        raise CoverageDeltaError(result.stderr.strip() or "git zero-context diff failed")
    hunks = [
        tuple(int(value or "1") for value in match.groups())
        for match in re.finditer(
            r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@",
            result.stdout,
            flags=re.MULTILINE,
        )
    ]
    mapping: dict[int, int] = {}
    old_cursor = new_cursor = 1
    for old_start, old_count, new_start, new_count in hunks:
        # A zero-count range is an inter-line anchor: ``-3,0`` means an
        # insertion *after* old line 3, while ``+3,0`` means a deletion after
        # new line 3. Convert both sides to the first changed-line cursor
        # before comparing their unchanged prefixes. This also maps the
        # boundary anchors ``-0,0`` / ``+0,0`` to cursor 1.
        old_change = old_start + (old_count == 0)
        new_change = new_start + (new_count == 0)
        unchanged = old_change - old_cursor
        if unchanged != new_change - new_cursor:
            raise CoverageDeltaError("git diff produced inconsistent unchanged ranges")
        for offset in range(unchanged):
            mapping[old_cursor + offset] = new_cursor + offset
        old_cursor = old_change + old_count
        new_cursor = new_change + new_count
    remaining = len(old) - old_cursor + 1
    if remaining != len(new) - new_cursor + 1:
        raise CoverageDeltaError("git diff produced inconsistent trailing ranges")
    for offset in range(max(remaining, 0)):
        mapping[old_cursor + offset] = new_cursor + offset
    return mapping


def coverage_losses(
    path: str,
    base_file: dict[str, Any],
    head_file: dict[str, Any],
    line_map: dict[int, int],
) -> list[dict[str, Any]]:
    head_lines = set(head_file.get("executed_lines", []))
    losses: list[dict[str, Any]] = []
    for line in base_file.get("executed_lines", []):
        mapped = line_map.get(line)
        if mapped is None or mapped not in head_lines:
            losses.append(
                {
                    "path": path,
                    "kind": "statement",
                    "base_coordinate": line,
                    "head_coordinate": mapped,
                    "disposition": "removed" if mapped is None else "mapped",
                }
            )
    head_branches = {tuple(branch) for branch in head_file.get("executed_branches", [])}

    def map_arc_point(point: int) -> int | None:
        # coverage.py represents entry/exit arc destinations as the negative
        # line number of the function boundary. Preserve that sign while
        # mapping its underlying source coordinate through the diff.
        if point < 0:
            mapped = line_map.get(-point)
            return -mapped if mapped is not None else None
        if point == 0:
            return 0
        return line_map.get(point)

    for branch in base_file.get("executed_branches", []):
        old_arc = tuple(branch)
        mapped_arc = tuple(map_arc_point(point) for point in old_arc)
        comparable = all(point is not None for point in mapped_arc)
        if not comparable or mapped_arc not in head_branches:
            losses.append(
                {
                    "path": path,
                    "kind": "branch",
                    "base_coordinate": list(old_arc),
                    "head_coordinate": list(mapped_arc) if comparable else None,
                    "disposition": "removed" if not comparable else "mapped",
                }
            )
    return losses


def _allowance_identity(row: dict[str, Any]) -> tuple[Any, ...]:
    base_coordinate = row["base_coordinate"]
    head_coordinate = row["head_coordinate"]
    if isinstance(base_coordinate, list):
        base_coordinate = tuple(base_coordinate)
    if isinstance(head_coordinate, list):
        head_coordinate = tuple(head_coordinate)
    return (
        row["path"],
        row["kind"],
        base_coordinate,
        head_coordinate,
        row["disposition"],
    )


def check_delta(
    *,
    base_coverage: dict[str, Any],
    head_coverage: dict[str, Any],
    affected: set[str],
    base_workspace: Path,
    head_workspace: Path,
    allowances: list[dict[str, Any]],
) -> list[dict[str, Any]]:
    losses: list[dict[str, Any]] = []
    for path in sorted(affected):
        base_file = base_coverage.get("files", {}).get(path)
        head_file = head_coverage.get("files", {}).get(path)
        if base_file is None:
            if head_file is None:
                raise CoverageDeltaError(f"coverage JSON is missing affected source file {path}")
            continue
        if head_file is None:
            head_file = {"executed_lines": [], "executed_branches": []}
        base_source = base_workspace / path
        head_source = head_workspace / path
        mapping = _line_map(
            base_source.read_text(encoding="utf-8") if base_source.is_file() else "",
            head_source.read_text(encoding="utf-8") if head_source.is_file() else "",
        )
        losses.extend(coverage_losses(path, base_file, head_file, mapping))
    allowance_map = {_allowance_identity(row): row for row in allowances}
    if len(allowance_map) != len(allowances):
        raise CoverageDeltaError("duplicate coverage allowance coordinate")
    loss_map = {_allowance_identity(row): row for row in losses}
    unmatched = sorted(set(loss_map) - set(allowance_map), key=str)
    stale = sorted(set(allowance_map) - set(loss_map), key=str)
    if unmatched:
        raise CoverageDeltaError(
            f"unexplained covered-coordinate losses: {unmatched}", losses=losses
        )
    if stale:
        raise CoverageDeltaError(f"stale coverage allowances: {stale}", losses=losses)
    return losses


def coverage_report(
    base_coverage: dict[str, Any], head_coverage: dict[str, Any], affected: set[str]
) -> list[dict[str, Any]]:
    result: list[dict[str, Any]] = []
    for path in sorted(affected):
        old = base_coverage.get("files", {}).get(path, {})
        new = head_coverage.get("files", {}).get(path, {})
        result.append(
            {
                "path": path,
                "base": old.get("summary", {}),
                "head": new.get("summary", {}),
                "base_covered_statements": len(old.get("executed_lines", [])),
                "head_covered_statements": len(new.get("executed_lines", [])),
                "base_covered_branches": len(old.get("executed_branches", [])),
                "head_covered_branches": len(new.get("executed_branches", [])),
            }
        )
    return result


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--base-json", type=Path, required=True)
    parser.add_argument("--head-json", type=Path, required=True)
    parser.add_argument("--changed-since", required=True)
    parser.add_argument("--base-workspace", type=Path, default=REPO_ROOT)
    parser.add_argument("--head-workspace", type=Path, default=REPO_ROOT)
    parser.add_argument("--scenario-policy", type=Path, default=SCENARIO_POLICY)
    parser.add_argument("--allowance-policy", type=Path, default=ALLOWANCE_POLICY)
    parser.add_argument("--report", type=Path)
    args = parser.parse_args(argv)
    report: dict[str, Any] = {
        "status": "error",
        "affected_paths": [],
        "files": [],
        "losses": [],
    }
    try:
        changed = changed_paths(args.changed_since)
        in_scope = any(path.startswith(IN_SCOPE_PREFIXES) for path in changed)
        if not in_scope:
            report = {"status": "out-of-scope", "affected_paths": [], "losses": []}
        else:
            affected = derive_affected_paths(
                changed=changed,
                base_workspace=args.base_workspace,
                head_workspace=args.head_workspace,
                base_revision=args.changed_since,
            )
            if not affected:
                raise CoverageDeltaError("in-scope change produced an empty coverage scope")
            report["affected_paths"] = sorted(affected)
            scenario = _load(args.scenario_policy)
            scenario_ids = {
                row["id"]: set(row.get("affected_paths", []))
                for row in scenario.get("scenarios", [])
            }
            allowance_policy = _load(args.allowance_policy)
            allowances = validate_allowances(
                allowance_policy,
                base_sha=args.changed_since,
                scenario_ids=scenario_ids,
            )
            base_coverage = _load(args.base_json)
            head_coverage = _load(args.head_json)
            report = {
                "status": "checking",
                "affected_paths": sorted(affected),
                "files": coverage_report(base_coverage, head_coverage, affected),
                "losses": [],
            }
            losses = check_delta(
                base_coverage=base_coverage,
                head_coverage=head_coverage,
                affected=affected,
                base_workspace=args.base_workspace,
                head_workspace=args.head_workspace,
                allowances=allowances,
            )
            report = {
                "status": "ok",
                "affected_paths": sorted(affected),
                "files": coverage_report(base_coverage, head_coverage, affected),
                "losses": losses,
            }
        rendered = json.dumps(report, indent=2, sort_keys=True) + "\n"
        if args.report:
            args.report.write_text(rendered, encoding="utf-8")
        print(rendered, end="")
    except (CoverageDeltaError, ValueError) as exc:
        report["status"] = "error"
        report["error"] = str(exc)
        if isinstance(exc, CoverageDeltaError) and exc.losses is not None:
            report["losses"] = exc.losses
        if args.report:
            args.report.write_text(
                json.dumps(report, indent=2, sort_keys=True) + "\n",
                encoding="utf-8",
            )
        parser.error(str(exc))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall