upfront 0.1.0__py3-none-any.whl

upfront/__init__.py

@@ -0,0 +1,7 @@
+"""upfront: see what your coding agent loads before your first prompt."""
+
+__version__ = "0.1.0"
+
+from upfront.report import Report, profile, profile_tools_file
+
+__all__ = ["Report", "__version__", "profile", "profile_tools_file"]

upfront/cli.py

@@ -0,0 +1,147 @@
+"""Command-line interface: ``upfront [PATH]``."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from upfront import __version__
+from upfront.discover import HARNESSES, discover
+from upfront.fetch import fetch_all
+from upfront.report import Report, build_report, profile_tools_file, servers_to_launch
+
+app = typer.Typer(add_completion=False, rich_markup_mode=None)
+
+
+LABEL_WIDTH = 46
+
+
+def _n(x: int) -> str:
+    return f"≈ {x:,}"
+
+
+def _row(label: str, value: str = "", note: str = "") -> str:
+    if len(label) > LABEL_WIDTH:
+        label = label[: LABEL_WIDTH - 1] + "…"
+    return f"{label:<{LABEL_WIDTH}} {value:>9}  {note}".rstrip()
+
+
+def _tidy(text: str, root: str) -> str:
+    """Shorten paths so pasted output doesn't leak the home directory."""
+    for prefix in (str(Path(root).resolve()), str(Path(root))):
+        if prefix not in ("", "."):
+            text = text.replace(prefix + "/", "")
+    return text.replace(str(Path.home()), "~")
+
+
+def render(report: Report, top: int) -> str:
+    root = report.root
+    header = root if root not in ("", ".") else _tidy(str(Path(root).resolve()), "/")
+    lines = [f"upfront {__version__} · {header} · tokens {report.tokenizer}"]
+    shown = [h for h in report.harnesses if not h.empty]
+    if not shown:
+        lines += ["", "Nothing configured: no MCP servers, skills or instruction files found."]
+    for h in shown:
+        lines += ["", _row(h.harness, _n(h.total), "before your first prompt")]
+        for s in h.servers:
+            label = f"  mcp {s.name} ({s.scope})"
+            if s.status == "ok":
+                lines.append(
+                    _row(f"  mcp {s.name} ({len(s.tools)} tools, {s.scope})", _n(s.tokens))
+                )
+                lines += [_row(f"      {t.name}", _n(t.tokens)) for t in s.tools[:top]]
+            elif s.status == "skipped":
+                lines.append(_row(label, "-", "not measured: no consent"))
+            else:
+                lines.append(_row(label, "-", f"not measured: {_tidy(s.error or '', root)}"))
+        if h.skills_count:
+            label = f"  skills ({h.skills_count}, name + description)"
+            body = f"bodies {_n(h.skills_body_tokens)} load on demand"
+            lines.append(_row(label, _n(h.skills_metadata_tokens), body))
+        for file in h.instructions:
+            lines.append(_row(f"  {_tidy(file.path, root)}", _n(file.tokens)))
+        lines += [f"  ! {_tidy(e, root)}" for e in h.errors]
+    findings = [f for h in report.harnesses for f in h.findings]
+    if findings:
+        lines += ["", "compatibility"]
+        for f in findings:
+            where = ".".join(x for x in (f.server, f.tool) if x) or "-"
+            lines.append(f"  {f.severity:<7} {f.harness:<11} {where}: {f.message}")
+            lines.append(f"          [{f.rule}] {f.source}")
+    if any(s.status == "skipped" for h in shown for s in h.servers):
+        lines += [
+            "",
+            "Servers were not started. Run with --yes to launch them and measure their tools.",
+        ]
+    return "\n".join(lines)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"upfront {__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+def main(
+    path: Annotated[Path, typer.Argument(help="Project directory.")] = Path("."),
+    harness: Annotated[
+        list[str] | None,
+        typer.Option("--harness", "-H", help=f"Only these harnesses: {', '.join(HARNESSES)}."),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Start/connect to configured servers without asking."),
+    ] = False,
+    as_json: Annotated[bool, typer.Option("--json", help="Print the report as JSON.")] = False,
+    budget: Annotated[
+        int | None, typer.Option(help="Exit 1 if any harness loads more tokens than this.")
+    ] = None,
+    strict: Annotated[
+        bool, typer.Option(help="Exit 1 on error-level compatibility findings.")
+    ] = False,
+    tools_file: Annotated[
+        Path | None, typer.Option(help="Measure a saved tools/list JSON instead of configs.")
+    ] = None,
+    top: Annotated[int, typer.Option(help="Heaviest tools to list per server.")] = 3,
+    timeout: Annotated[float, typer.Option(help="Seconds per server.")] = 20,
+    version: Annotated[
+        bool, typer.Option("--version", callback=_version, is_eager=True, help="Show the version.")
+    ] = False,
+) -> None:
+    """See what your coding agents load before your first prompt."""
+    unknown = set(harness or []) - set(HARNESSES)
+    if unknown:
+        raise typer.BadParameter(f"unknown harness {', '.join(sorted(unknown))}", param_hint="-H")
+
+    if tools_file:
+        report = profile_tools_file(tools_file, only=harness)
+    else:
+        d = discover(path, only=harness)
+        specs = servers_to_launch(d)
+        launch = yes
+        if specs and not yes and sys.stdin.isatty():
+            typer.echo("upfront will start or connect to these MCP servers to read their tools:")
+            for s in specs:
+                typer.echo(f"  [{s.harness}] {s.name}: {s.target}")
+            launch = typer.confirm("Continue?", default=False)
+        report = build_report(d, fetch_all(specs, timeout=timeout) if launch else [])
+
+    typer.echo(report.to_json() if as_json else render(report, top))
+
+    failed = False
+    if budget is not None:
+        for h in report.harnesses:
+            if h.total > budget:
+                failed = True
+                if not as_json:
+                    typer.echo(
+                        f"{h.harness}: {h.total:,} tokens is over budget ({budget:,})", err=True
+                    )
+    if strict and any(f.severity == "error" for h in report.harnesses for f in h.findings):
+        failed = True
+    if failed:
+        raise typer.Exit(1)

upfront/compat.py

@@ -0,0 +1,227 @@
+"""Static compatibility checks for MCP tool definitions, per client.
+
+Every rule cites the documentation or the *open* issue it comes from. Problems that clients
+have already fixed (several old ``$defs``/64-character reports) are deliberately not rules:
+a false "this breaks" is worse than no warning.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from upfront.discover import Skill
+
+Severity = Literal["error", "warning", "info"]
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    harnesses: tuple[str, ...]
+    severity: Severity
+    summary: str
+    source: str
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule: str
+    harness: str
+    severity: Severity
+    server: str
+    tool: str
+    message: str
+    source: str
+
+
+RULES: dict[str, Rule] = {
+    r.id: r
+    for r in (
+        Rule(
+            "openai-tool-name",
+            ("codex",),
+            "error",
+            "OpenAI function names allow a-z, A-Z, 0-9, _ and -, up to 64 characters",
+            "https://github.com/openai/openai-python/blob/main/src/openai/types/shared_params/function_definition.py",
+        ),
+        Rule(
+            "anthropic-tool-name",
+            ("claude-code",),
+            "error",
+            "Claude tool names must match ^[a-zA-Z0-9_-]{1,128}$ after the mcp__<server>__ prefix",
+            "https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools",
+        ),
+        Rule(
+            "gemini-tool-name",
+            ("gemini-cli",),
+            "error",
+            "Gemini function names start with a letter or _; then a-zA-Z0-9_.:-, up to 128",
+            "https://github.com/googleapis/python-genai/blob/main/google/genai/types.py",
+        ),
+        Rule(
+            "claude-ref-params",
+            ("claude-code",),
+            "warning",
+            "Parameters defined through $ref are sent to the server as JSON strings",
+            "https://github.com/anthropics/claude-code/issues/18260",
+        ),
+        Rule(
+            "opencode-unknown-format",
+            ("opencode",),
+            "info",
+            "Non-standard JSON Schema 'format' values make OpenCode log warnings",
+            "https://github.com/anomalyco/opencode/issues/15161",
+        ),
+        Rule(
+            "codex-skills-budget",
+            ("codex",),
+            "warning",
+            "Codex caps the initial skills list at 2% of the context window (8,000 characters "
+            "when the window is unknown) and shortens or drops skills beyond it",
+            "https://learn.chatgpt.com/docs/build-skills",
+        ),
+    )
+}
+
+_OPENAI_NAME = re.compile(r"^[a-zA-Z0-9_-]{1,64}$")
+_ANTHROPIC_NAME = re.compile(r"^[a-zA-Z0-9_-]{1,128}$")
+_SERVER_SEGMENT = re.compile(r"[^a-zA-Z0-9_-]")
+_GEMINI_NAME = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_.:-]{0,127}$")
+
+# JSON Schema 2020-12 defined formats (validation vocabulary, section 7.3).
+STANDARD_FORMATS = frozenset(
+    {
+        "date-time",
+        "date",
+        "time",
+        "duration",
+        "email",
+        "idn-email",
+        "hostname",
+        "idn-hostname",
+        "ipv4",
+        "ipv6",
+        "uri",
+        "uri-reference",
+        "iri",
+        "iri-reference",
+        "uuid",
+        "uri-template",
+        "json-pointer",
+        "relative-json-pointer",
+        "regex",
+    }
+)
+
+CODEX_SKILLS_FALLBACK_CHARS = 8000
+
+
+def _walk(node: Any) -> Iterator[dict[str, Any]]:
+    if isinstance(node, dict):
+        yield node
+        for v in node.values():
+            yield from _walk(v)
+    elif isinstance(node, list):
+        for v in node:
+            yield from _walk(v)
+
+
+def _finding(rule_id: str, harness: str, server: str, tool: str, message: str) -> Finding:
+    r = RULES[rule_id]
+    return Finding(rule_id, harness, r.severity, server, tool, message, r.source)
+
+
+def check_tools(harness: str, server: str, tools: list[dict[str, Any]]) -> list[Finding]:
+    """Findings for one server's tools as seen by ``harness``."""
+    out: list[Finding] = []
+    for tool in tools:
+        name = str(tool.get("name", ""))
+        schema = tool.get("inputSchema") or {}
+        nodes = list(_walk(schema))
+        if harness == "codex" and not _OPENAI_NAME.match(name):
+            out.append(
+                _finding(
+                    "openai-tool-name",
+                    harness,
+                    server,
+                    name,
+                    f"'{name}' ({len(name)} chars) is not a valid OpenAI function name",
+                )
+            )
+        if harness == "claude-code":
+            full = f"mcp__{_SERVER_SEGMENT.sub('_', server)}__{name}"
+            if not _ANTHROPIC_NAME.match(full):
+                out.append(
+                    _finding(
+                        "anthropic-tool-name",
+                        harness,
+                        server,
+                        name,
+                        f"'{full}' ({len(full)} chars) is not a valid Claude tool name",
+                    )
+                )
+            if any("$ref" in n for n in nodes):
+                out.append(
+                    _finding(
+                        "claude-ref-params",
+                        harness,
+                        server,
+                        name,
+                        "uses $ref; Claude Code may send those arguments as strings",
+                    )
+                )
+        if harness == "gemini-cli" and not _GEMINI_NAME.match(name):
+            out.append(
+                _finding(
+                    "gemini-tool-name",
+                    harness,
+                    server,
+                    name,
+                    f"'{name}' is not a valid Gemini function name",
+                )
+            )
+        if harness == "opencode":
+            odd = sorted(
+                {
+                    str(n["format"])
+                    for n in nodes
+                    if isinstance(n.get("format"), str) and n["format"] not in STANDARD_FORMATS
+                }
+            )
+            if odd:
+                out.append(
+                    _finding(
+                        "opencode-unknown-format",
+                        harness,
+                        server,
+                        name,
+                        f"non-standard format: {', '.join(odd)}",
+                    )
+                )
+    return out
+
+
+def codex_skills_chars(skills: list[Skill]) -> int:
+    """Approximate size of Codex's initial skills list: name, description and path per skill."""
+    return sum(len(s.name) + len(s.description) + len(str(s.path)) for s in skills)
+
+
+def check_skills(harness: str, skills: list[Skill]) -> list[Finding]:
+    if harness != "codex":
+        return []
+    chars = codex_skills_chars(skills)
+    if chars <= CODEX_SKILLS_FALLBACK_CHARS:
+        return []
+    return [
+        _finding(
+            "codex-skills-budget",
+            harness,
+            "",
+            "",
+            f"{len(skills)} skills ≈ {chars:,} characters of metadata, over Codex's "
+            f"{CODEX_SKILLS_FALLBACK_CHARS:,}-character fallback budget",
+        )
+    ]

upfront/discover.py

@@ -0,0 +1,439 @@
+"""Find the MCP servers, skills and instruction files each coding agent loads up front.
+
+Config formats follow each harness's documentation:
+
+- Claude Code: https://code.claude.com/docs/en/mcp (``.mcp.json``, ``~/.claude.json``)
+- Codex: https://learn.chatgpt.com/docs/extend/mcp (``[mcp_servers.<name>]`` in
+  ``.codex/config.toml`` and ``~/.codex/config.toml``); skills in ``.agents/skills``
+- Gemini CLI: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
+  (``mcpServers`` in ``.gemini/settings.json``; ``url`` is SSE, ``httpUrl`` is Streamable HTTP)
+- OpenCode: https://opencode.ai/docs/mcp-servers (``mcp`` in ``opencode.json[c]``)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tomllib
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+Harness = Literal["claude-code", "codex", "gemini-cli", "opencode"]
+HARNESSES: tuple[Harness, ...] = ("claude-code", "codex", "gemini-cli", "opencode")
+Transport = Literal["stdio", "http", "sse"]
+Scope = Literal["project", "local", "user"]
+
+
+@dataclass
+class ServerSpec:
+    """One configured MCP server, as a given harness would start it."""
+
+    harness: Harness
+    name: str
+    scope: Scope
+    source: Path
+    transport: Transport
+    command: str | None = None
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    cwd: str | None = None
+    url: str | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def target(self) -> str:
+        """The command line or URL, as shown to the user before launching."""
+        if self.transport == "stdio":
+            return " ".join([self.command or "", *self.args]).strip()
+        return self.url or ""
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    body: str
+    path: Path
+
+
+@dataclass
+class InstructionFile:
+    path: Path
+    text: str
+
+
+@dataclass
+class HarnessContext:
+    harness: Harness
+    servers: list[ServerSpec] = field(default_factory=list)
+    skills: list[Skill] = field(default_factory=list)
+    instructions: list[InstructionFile] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Discovery:
+    root: Path
+    harnesses: dict[Harness, HarnessContext]
+
+
+# --------------------------------------------------------------------------- #
+# Small parsers
+# --------------------------------------------------------------------------- #
+
+_VAR = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}")
+
+
+def expand(value: str, env: Mapping[str, str]) -> str:
+    """Claude Code's ``${VAR}`` / ``${VAR:-default}`` expansion; unknown vars stay literal."""
+
+    def sub(m: re.Match[str]) -> str:
+        name, default = m.group(1), m.group(2)
+        if name in env:
+            return env[name]
+        return default if default is not None else m.group(0)
+
+    return _VAR.sub(sub, value)
+
+
+def strip_jsonc(text: str) -> str:
+    """Remove // and /* */ comments and trailing commas outside of strings."""
+    out: list[str] = []
+    i, n, in_str = 0, len(text), False
+    while i < n:
+        c = text[i]
+        if in_str:
+            out.append(c)
+            if c == "\\" and i + 1 < n:
+                out.append(text[i + 1])
+                i += 1
+            elif c == '"':
+                in_str = False
+        elif c == '"':
+            in_str = True
+            out.append(c)
+        elif text.startswith("//", i):
+            while i < n and text[i] != "\n":
+                i += 1
+            continue
+        elif text.startswith("/*", i):
+            end = text.find("*/", i + 2)
+            i = n if end == -1 else end + 2
+            continue
+        else:
+            out.append(c)
+        i += 1
+    return re.sub(r",(\s*[}\]])", r"\1", "".join(out))
+
+
+def _load(path: Path, ctx: HarnessContext, kind: Literal["json", "jsonc", "toml"]) -> Any:
+    if not path.is_file():
+        return None
+    try:
+        text = path.read_text(encoding="utf-8")
+        if kind == "toml":
+            return tomllib.loads(text)
+        return json.loads(strip_jsonc(text) if kind == "jsonc" else text)
+    except (OSError, ValueError) as e:
+        ctx.errors.append(f"{path}: could not parse ({e})")
+        return None
+
+
+def _str_map(value: Any) -> dict[str, str]:
+    return {str(k): str(v) for k, v in value.items()} if isinstance(value, dict) else {}
+
+
+def _str_list(value: Any) -> list[str]:
+    return [str(v) for v in value] if isinstance(value, list) else []
+
+
+# --------------------------------------------------------------------------- #
+# Per-harness readers
+# --------------------------------------------------------------------------- #
+
+
+def _claude_servers(
+    ctx: HarnessContext, entries: Any, scope: Scope, source: Path, env: Mapping[str, str]
+) -> None:
+    if not isinstance(entries, dict):
+        return
+    for name, e in entries.items():
+        if not isinstance(e, dict):
+            continue
+        kind = str(e.get("type", "stdio" if "command" in e else ""))
+
+        def x(v: Any) -> str:
+            return expand(str(v), env)
+
+        if kind == "stdio" and "command" in e:
+            ctx.servers.append(
+                ServerSpec(
+                    "claude-code",
+                    name,
+                    scope,
+                    source,
+                    "stdio",
+                    command=x(e["command"]),
+                    args=[x(a) for a in _str_list(e.get("args"))],
+                    env={k: x(v) for k, v in _str_map(e.get("env")).items()},
+                )
+            )
+        elif kind in ("http", "streamable-http", "sse") and "url" in e:
+            ctx.servers.append(
+                ServerSpec(
+                    "claude-code",
+                    name,
+                    scope,
+                    source,
+                    "sse" if kind == "sse" else "http",
+                    url=x(e["url"]),
+                    headers={k: x(v) for k, v in _str_map(e.get("headers")).items()},
+                )
+            )
+        else:
+            ctx.errors.append(
+                f'{source}: server \'{name}\' skipped: needs "command", or "type": '
+                '"http"/"sse" with "url" (Claude Code skips it too)'
+            )
+
+
+def _claude(root: Path, home: Path, env: Mapping[str, str]) -> HarnessContext:
+    ctx = HarnessContext("claude-code")
+    project = _load(root / ".mcp.json", ctx, "json")
+    if isinstance(project, dict):
+        _claude_servers(ctx, project.get("mcpServers"), "project", root / ".mcp.json", env)
+    user = _load(home / ".claude.json", ctx, "json")
+    if isinstance(user, dict):
+        src = home / ".claude.json"
+        _claude_servers(ctx, user.get("mcpServers"), "user", src, env)
+        projects = user.get("projects") or {}
+        local = projects.get(str(root)) or projects.get(str(root.resolve()))
+        if isinstance(local, dict):
+            _claude_servers(ctx, local.get("mcpServers"), "local", src, env)
+    # Claude Code reads AGENTS.md when the project has no CLAUDE.md.
+    _instructions(
+        ctx, [root / "CLAUDE.md"] if (root / "CLAUDE.md").is_file() else [root / "AGENTS.md"]
+    )
+    _instructions(ctx, [home / ".claude" / "CLAUDE.md"])
+    _skills(ctx, [root / ".claude" / "skills", home / ".claude" / "skills"])
+    return ctx
+
+
+def _codex(root: Path, home: Path) -> HarnessContext:
+    ctx = HarnessContext("codex")
+    sources: list[tuple[Path, Scope]] = [
+        (root / ".codex" / "config.toml", "project"),
+        (home / ".codex" / "config.toml", "user"),
+    ]
+    for path, scope in sources:
+        data = _load(path, ctx, "toml")
+        servers = data.get("mcp_servers") if isinstance(data, dict) else None
+        for name, e in (servers or {}).items():
+            if not isinstance(e, dict) or e.get("enabled") is False:
+                continue
+            if "command" in e:
+                ctx.servers.append(
+                    ServerSpec(
+                        "codex",
+                        name,
+                        scope,
+                        path,
+                        "stdio",
+                        command=str(e["command"]),
+                        args=_str_list(e.get("args")),
+                        env=_str_map(e.get("env")),
+                        cwd=str(e["cwd"]) if "cwd" in e else None,
+                    )
+                )
+            elif "url" in e:
+                ctx.servers.append(
+                    ServerSpec("codex", name, scope, path, "http", url=str(e["url"]))
+                )
+    _instructions(ctx, [root / "AGENTS.md", home / ".codex" / "AGENTS.md"])
+    _skills(ctx, [root / ".agents" / "skills", home / ".agents" / "skills"])
+    return ctx
+
+
+def _gemini(root: Path, home: Path) -> HarnessContext:
+    ctx = HarnessContext("gemini-cli")
+    sources: list[tuple[Path, Scope]] = [
+        (root / ".gemini" / "settings.json", "project"),
+        (home / ".gemini" / "settings.json", "user"),
+    ]
+    for path, scope in sources:
+        data = _load(path, ctx, "json")
+        servers = data.get("mcpServers") if isinstance(data, dict) else None
+        for name, e in (servers or {}).items():
+            if not isinstance(e, dict):
+                continue
+            headers = _str_map(e.get("headers"))
+            if "command" in e:
+                ctx.servers.append(
+                    ServerSpec(
+                        "gemini-cli",
+                        name,
+                        scope,
+                        path,
+                        "stdio",
+                        command=str(e["command"]),
+                        args=_str_list(e.get("args")),
+                        env=_str_map(e.get("env")),
+                        cwd=str(e["cwd"]) if "cwd" in e else None,
+                    )
+                )
+            elif "httpUrl" in e:
+                ctx.servers.append(
+                    ServerSpec(
+                        "gemini-cli",
+                        name,
+                        scope,
+                        path,
+                        "http",
+                        url=str(e["httpUrl"]),
+                        headers=headers,
+                    )
+                )
+            elif "url" in e:
+                ctx.servers.append(
+                    ServerSpec(
+                        "gemini-cli", name, scope, path, "sse", url=str(e["url"]), headers=headers
+                    )
+                )
+    _instructions(ctx, [root / "GEMINI.md", home / ".gemini" / "GEMINI.md"])
+    return ctx
+
+
+def _opencode(root: Path, home: Path) -> HarnessContext:
+    ctx = HarnessContext("opencode")
+    user_dir = home / ".config" / "opencode"
+    candidates: list[tuple[Path, Scope]] = [
+        (root / "opencode.jsonc", "project"),
+        (root / "opencode.json", "project"),
+        (user_dir / "opencode.jsonc", "user"),
+        (user_dir / "opencode.json", "user"),
+    ]
+    for path, scope in candidates:
+        data = _load(path, ctx, "jsonc")
+        servers = data.get("mcp") if isinstance(data, dict) else None
+        for name, e in (servers or {}).items():
+            if not isinstance(e, dict) or e.get("enabled") is False:
+                continue
+            if e.get("type") == "local":
+                cmd = _str_list(e.get("command"))
+                if cmd:
+                    ctx.servers.append(
+                        ServerSpec(
+                            "opencode",
+                            name,
+                            scope,
+                            path,
+                            "stdio",
+                            command=cmd[0],
+                            args=cmd[1:],
+                            env=_str_map(e.get("environment")),
+                        )
+                    )
+            elif e.get("type") == "remote" and "url" in e:
+                ctx.servers.append(
+                    ServerSpec(
+                        "opencode",
+                        name,
+                        scope,
+                        path,
+                        "http",
+                        url=str(e["url"]),
+                        headers=_str_map(e.get("headers")),
+                    )
+                )
+    _instructions(ctx, [root / "AGENTS.md", user_dir / "AGENTS.md"])
+    _skills(
+        ctx,
+        [
+            root / ".opencode" / "skills",
+            root / ".claude" / "skills",
+            root / ".agents" / "skills",
+            user_dir / "skills",
+            home / ".claude" / "skills",
+            home / ".agents" / "skills",
+        ],
+    )
+    return ctx
+
+
+# --------------------------------------------------------------------------- #
+# Skills and instruction files
+# --------------------------------------------------------------------------- #
+
+_FRONTMATTER = re.compile(r"\A---\s*\n(.*?)\n---\s*\n?", re.S)
+
+
+def parse_skill(path: Path) -> Skill:
+    text = path.read_text(encoding="utf-8")
+    meta: dict[str, str] = {}
+    body = text
+    m = _FRONTMATTER.match(text)
+    if m:
+        body = text[m.end() :]
+        for line in m.group(1).splitlines():
+            key, sep, value = line.partition(":")
+            if sep and not line.startswith((" ", "\t")):
+                meta[key.strip()] = value.strip().strip("\"'")
+    return Skill(meta.get("name", path.parent.name), meta.get("description", ""), body, path)
+
+
+def _skills(ctx: HarnessContext, dirs: Iterable[Path]) -> None:
+    seen = {s.name for s in ctx.skills}
+    for d in dirs:
+        for path in sorted(d.glob("*/SKILL.md")) if d.is_dir() else []:
+            try:
+                s = parse_skill(path)
+            except (OSError, UnicodeDecodeError) as e:
+                ctx.errors.append(f"{path}: could not read ({e})")
+                continue
+            if s.name not in seen:  # the first location wins, like the harnesses' precedence
+                seen.add(s.name)
+                ctx.skills.append(s)
+
+
+def _instructions(ctx: HarnessContext, paths: Iterable[Path]) -> None:
+    for p in paths:
+        if p.is_file():
+            try:
+                ctx.instructions.append(InstructionFile(p, p.read_text(encoding="utf-8")))
+            except (OSError, UnicodeDecodeError) as e:
+                ctx.errors.append(f"{p}: could not read ({e})")
+
+
+# --------------------------------------------------------------------------- #
+# Entry point
+# --------------------------------------------------------------------------- #
+
+
+def discover(
+    root: Path,
+    *,
+    home: Path | None = None,
+    env: Mapping[str, str] | None = None,
+    only: Iterable[str] | None = None,
+) -> Discovery:
+    """Read every supported config under ``root`` (project) and ``home`` (user scope)."""
+    home = home or Path.home()
+    env = dict(os.environ) if env is None else env
+    wanted = [h for h in HARNESSES if only is None or h in set(only)]
+    readers: dict[Harness, Any] = {
+        "claude-code": lambda: _claude(root, home, env),
+        "codex": lambda: _codex(root, home),
+        "gemini-cli": lambda: _gemini(root, home),
+        "opencode": lambda: _opencode(root, home),
+    }
+    found: dict[Harness, HarnessContext] = {h: readers[h]() for h in wanted}
+    for ctx in found.values():
+        for spec in ctx.servers:
+            # Agents start stdio servers from the project directory; relative cwds are
+            # resolved against it (Gemini CLI documents "cwd": "./server-directory").
+            if spec.transport == "stdio":
+                spec.cwd = str(root / spec.cwd) if spec.cwd else str(root)
+    return Discovery(root, found)

upfront/fetch.py

@@ -0,0 +1,132 @@
+"""Connect to MCP servers and collect their full ``tools/list``, exactly as a client would."""
+
+from __future__ import annotations
+
+import tempfile
+from contextlib import AbstractAsyncContextManager
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import anyio
+import httpx2
+from mcp import Client, StdioServerParameters
+from mcp.client.sse import sse_client
+from mcp.client.stdio import stdio_client
+from mcp.client.streamable_http import streamable_http_client
+
+from upfront.discover import ServerSpec
+
+Status = Literal["ok", "error", "skipped"]
+
+
+@dataclass
+class ServerResult:
+    spec: ServerSpec
+    status: Status
+    tools: list[dict[str, Any]] = field(default_factory=list)
+    error: str | None = None
+
+
+def _key(spec: ServerSpec) -> tuple[Any, ...]:
+    return (
+        spec.transport,
+        spec.command,
+        tuple(spec.args),
+        tuple(sorted(spec.env.items())),
+        spec.cwd,
+        spec.url,
+        tuple(sorted(spec.headers.items())),
+    )
+
+
+def _transport(
+    spec: ServerSpec, errlog: Any, statuses: list[int]
+) -> AbstractAsyncContextManager[Any]:
+    async def record(response: httpx2.Response) -> None:
+        statuses.append(response.status_code)
+
+    if spec.transport == "stdio":
+        params = StdioServerParameters(
+            command=spec.command or "", args=spec.args, env=spec.env or None, cwd=spec.cwd
+        )
+        return stdio_client(params, errlog=errlog)
+    if spec.transport == "sse":
+        return sse_client(spec.url or "", headers=dict(spec.headers) or None)
+    client = httpx2.AsyncClient(
+        headers=spec.headers, follow_redirects=True, event_hooks={"response": [record]}
+    )
+    return streamable_http_client(spec.url or "", http_client=client)
+
+
+def _describe(exc: BaseException, statuses: list[int]) -> str:
+    """Turn nested anyio/httpx exception groups into one short, actionable line."""
+    auth = [c for c in statuses if c in (401, 403)]
+    if auth:
+        return f"auth required (HTTP {auth[0]}); not measured"
+    while isinstance(exc, BaseExceptionGroup) and exc.exceptions:
+        exc = exc.exceptions[0]
+    text = f"{type(exc).__name__}: {exc}".strip().rstrip(":")
+    if isinstance(exc, FileNotFoundError):
+        return f"command not found: {exc.filename or exc}"
+    return text
+
+
+async def _list_tools(
+    spec: ServerSpec, timeout: float, statuses: list[int], errlog: Any
+) -> list[dict[str, Any]]:
+    tools: list[dict[str, Any]] = []
+    with anyio.fail_after(timeout):
+        transport = _transport(spec, errlog, statuses)
+        async with Client(transport, read_timeout_seconds=timeout) as client:
+            cursor: str | None = None
+            while True:
+                page = await client.list_tools(cursor=cursor)
+                tools += [t.model_dump(by_alias=True, exclude_none=True) for t in page.tools]
+                cursor = page.next_cursor
+                if not cursor:
+                    return tools
+
+
+async def fetch_one(spec: ServerSpec, timeout: float = 20) -> ServerResult:
+    """Fetch one server's tools. Never raises: failures become ``status="error"``."""
+    statuses: list[int] = []
+    with tempfile.TemporaryFile("w+", encoding="utf-8", errors="replace") as errlog:
+        try:
+            return ServerResult(spec, "ok", await _list_tools(spec, timeout, statuses, errlog))
+        except TimeoutError:
+            error = f"timed out after {timeout:g}s"
+        except Exception as e:
+            error = _describe(e, statuses)
+        errlog.seek(0)
+        stderr = [line.strip() for line in errlog.read().splitlines() if line.strip()]
+    if stderr:  # a server that exits early usually says why on stderr
+        error += f"; server said: {stderr[-1][:200]}"
+    return ServerResult(spec, "error", error=error)
+
+
+def fetch_all(
+    specs: list[ServerSpec], *, timeout: float = 20, concurrency: int = 4
+) -> list[ServerResult]:
+    """Fetch every server, launching each distinct command/URL once. Order matches ``specs``."""
+    unique: dict[tuple[Any, ...], ServerSpec] = {}
+    for s in specs:
+        unique.setdefault(_key(s), s)
+    done: dict[tuple[Any, ...], ServerResult] = {}
+
+    async def run() -> None:
+        limiter = anyio.CapacityLimiter(concurrency)
+
+        async def one(key: tuple[Any, ...], spec: ServerSpec) -> None:
+            async with limiter:
+                done[key] = await fetch_one(spec, timeout)
+
+        async with anyio.create_task_group() as tg:
+            for key, spec in unique.items():
+                tg.start_soon(one, key, spec)
+
+    anyio.run(run)
+    results = []
+    for s in specs:
+        shared = done[_key(s)]
+        results.append(ServerResult(s, shared.status, shared.tools, shared.error))
+    return results

upfront/report.py

@@ -0,0 +1,157 @@
+"""Assemble discovery, fetch, token counts and compat findings into one report."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from upfront import compat, tokens
+from upfront.discover import HARNESSES, Discovery, Harness, ServerSpec, discover
+from upfront.fetch import ServerResult, Status, fetch_all
+
+
+@dataclass
+class ToolUsage:
+    name: str
+    tokens: int
+
+
+@dataclass
+class ServerUsage:
+    name: str
+    scope: str
+    transport: str
+    target: str
+    source: str
+    status: Status
+    error: str | None = None
+    tools: list[ToolUsage] = field(default_factory=list)
+
+    @property
+    def tokens(self) -> int:
+        return sum(t.tokens for t in self.tools)
+
+
+@dataclass
+class FileUsage:
+    path: str
+    tokens: int
+
+
+@dataclass
+class HarnessReport:
+    harness: Harness
+    servers: list[ServerUsage] = field(default_factory=list)
+    skills_count: int = 0
+    skills_metadata_tokens: int = 0
+    skills_body_tokens: int = 0
+    instructions: list[FileUsage] = field(default_factory=list)
+    findings: list[compat.Finding] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def total(self) -> int:
+        """Tokens loaded before the first prompt: tools + skill metadata + instruction files."""
+        servers = sum(s.tokens for s in self.servers if s.status == "ok")
+        return servers + self.skills_metadata_tokens + sum(f.tokens for f in self.instructions)
+
+    @property
+    def empty(self) -> bool:
+        return not (self.servers or self.skills_count or self.instructions or self.errors)
+
+
+@dataclass
+class Report:
+    root: str
+    tokenizer: str
+    harnesses: list[HarnessReport]
+
+    def to_dict(self) -> dict[str, Any]:
+        def harness(h: HarnessReport) -> dict[str, Any]:
+            d = asdict(h)
+            d["total"] = h.total
+            for s, raw in zip(h.servers, d["servers"], strict=True):
+                raw["tokens"] = s.tokens
+            return d
+
+        return {
+            "root": self.root,
+            "tokenizer": self.tokenizer,
+            "harnesses": [harness(h) for h in self.harnesses],
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2, ensure_ascii=False)
+
+
+def _server_usage(result: ServerResult, harness: str) -> tuple[ServerUsage, list[compat.Finding]]:
+    spec = result.spec
+    usage = ServerUsage(
+        spec.name, spec.scope, spec.transport, spec.target, str(spec.source),
+        result.status, result.error,
+        sorted((ToolUsage(str(t.get("name", "")), tokens.tool_tokens(t)) for t in result.tools),
+               key=lambda t: -t.tokens),
+    )  # fmt: skip
+    findings = compat.check_tools(harness, spec.name, result.tools) if result.status == "ok" else []
+    return usage, findings
+
+
+def build_report(discovery: Discovery, results: Iterable[ServerResult]) -> Report:
+    by_spec = {id(r.spec): r for r in results}
+    out: list[HarnessReport] = []
+    for name, ctx in discovery.harnesses.items():
+        h = HarnessReport(name, errors=list(ctx.errors))
+        for spec in ctx.servers:
+            r = by_spec.get(id(spec)) or ServerResult(spec, "skipped")
+            usage, findings = _server_usage(r, name)
+            h.servers.append(usage)
+            h.findings += findings
+        h.servers.sort(key=lambda s: -s.tokens)
+        h.skills_count = len(ctx.skills)
+        for s in ctx.skills:
+            meta, body = tokens.skill_tokens(s)
+            h.skills_metadata_tokens += meta
+            h.skills_body_tokens += body
+        h.findings += compat.check_skills(name, ctx.skills)
+        h.instructions = [FileUsage(str(f.path), tokens.count(f.text)) for f in ctx.instructions]
+        out.append(h)
+    return Report(str(discovery.root), tokens.tokenizer_name(), out)
+
+
+def servers_to_launch(discovery: Discovery) -> list[ServerSpec]:
+    return [s for ctx in discovery.harnesses.values() for s in ctx.servers]
+
+
+def profile(
+    root: Path | str = ".",
+    *,
+    home: Path | None = None,
+    launch: bool = False,
+    only: Iterable[str] | None = None,
+    timeout: float = 20,
+) -> Report:
+    """Library entry point: discover configs under ``root`` and measure them.
+
+    ``launch=False`` (the default) never starts a process or opens a connection; servers are
+    reported as ``skipped``. See ADR-0004.
+    """
+    d = discover(Path(root), home=home, only=only)
+    results = fetch_all(servers_to_launch(d), timeout=timeout) if launch else []
+    return build_report(d, results)
+
+
+def profile_tools_file(path: Path, *, only: Iterable[str] | None = None) -> Report:
+    """Measure a saved ``tools/list`` JSON (``{"tools": [...]}`` or a list) for each client."""
+    data = json.loads(path.read_text(encoding="utf-8"))
+    tools = data["tools"] if isinstance(data, dict) else data
+    wanted = [h for h in HARNESSES if only is None or h in set(only)]
+    name = path.name.split(".")[0]  # "github.tools.json" -> "github"
+    out = []
+    for harness in wanted:
+        spec = ServerSpec(harness, name, "project", path, "stdio", command="(tools file)")
+        usage, findings = _server_usage(ServerResult(spec, "ok", tools), harness)
+        out.append(HarnessReport(harness, servers=[usage], findings=findings))
+    return Report(str(path), tokens.tokenizer_name(), out)

upfront/tokens.py

@@ -0,0 +1,50 @@
+"""Token estimates for what a client sends: tool definitions, skill metadata, instruction files.
+
+One tokenizer (``o200k_base``) is used for every harness; numbers are estimates (ADR-0003).
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from functools import lru_cache
+from typing import Any
+
+import tiktoken
+
+from upfront.discover import Skill
+
+ENCODING = "o200k_base"
+
+# Fields of an MCP Tool that clients forward to the model. `_meta` and `icons` are client-side.
+WIRE_FIELDS = ("name", "title", "description", "inputSchema", "outputSchema", "annotations")
+
+
+@lru_cache(maxsize=1)
+def _encoder() -> tiktoken.Encoding | None:
+    try:
+        return tiktoken.get_encoding(ENCODING)
+    except Exception:  # offline, blocked CDN, corrupt cache: fall back to an estimate
+        return None
+
+
+def tokenizer_name() -> str:
+    return ENCODING if _encoder() is not None else "chars/4 estimate (tokenizer unavailable)"
+
+
+def count(text: str) -> int:
+    enc = _encoder()
+    if enc is None:
+        return math.ceil(len(text) / 4)
+    return len(enc.encode(text, disallowed_special=()))
+
+
+def tool_tokens(tool: dict[str, Any]) -> int:
+    """Tokens for one tool definition as compact JSON of its wire fields."""
+    wire = {k: tool[k] for k in WIRE_FIELDS if k in tool}
+    return count(json.dumps(wire, separators=(",", ":"), ensure_ascii=False))
+
+
+def skill_tokens(skill: Skill) -> tuple[int, int]:
+    """(metadata loaded up front, body loaded when the skill is used)."""
+    return count(f"{skill.name}: {skill.description}"), count(skill.body)

upfront-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: upfront
+Version: 0.1.0
+Summary: See how many tokens your MCP servers, skills and instruction files cost a coding agent before your first prompt, and which tools break in which client.
+Project-URL: Homepage, https://github.com/thanatchon36/upfront
+Project-URL: Issues, https://github.com/thanatchon36/upfront/issues
+Project-URL: Changelog, https://github.com/thanatchon36/upfront/blob/main/CHANGELOG.md
+Author: Thanatchon
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,codex,context-window,gemini-cli,llm,mcp,model-context-protocol,opencode,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mcp>=2.3.0
+Requires-Dist: tiktoken>=0.14.0
+Requires-Dist: typer>=0.27.3
+Description-Content-Type: text/markdown
+
+# upfront
+
+[![ci](https://github.com/thanatchon36/upfront/actions/workflows/ci.yml/badge.svg)](https://github.com/thanatchon36/upfront/actions/workflows/ci.yml)
+[![coverage](https://codecov.io/gh/thanatchon36/upfront/graph/badge.svg)](https://codecov.io/gh/thanatchon36/upfront)
+[![PyPI](https://img.shields.io/pypi/v/upfront)](https://pypi.org/project/upfront/)
+[![Python](https://img.shields.io/pypi/pyversions/upfront)](https://pypi.org/project/upfront/)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/thanatchon36/upfront/blob/main/LICENSE)
+
+See how many tokens your MCP servers, skills and instruction files cost a coding agent before
+you type a word, and which tools will break in Claude Code, Codex, Gemini CLI or OpenCode.
+
+## The problem
+
+> "Claude Code sends 33k tokens before reading the prompt; OpenCode sends 7k"
+> — [Hacker News, 706 points](https://news.ycombinator.com/item?id=48883275); finding out took a logging proxy.
+
+Every connected MCP server puts all of its tool schemas into the context, every skill adds its
+description, and AGENTS.md / CLAUDE.md ride along on every request. Usage limits arrive early,
+and Codex starts dropping skills ([codex#19679](https://github.com/openai/codex/issues/19679))
+and MCP tools ([codex#44308](https://github.com/openai/codex/issues/44308)) once budgets run
+out. Claude Code's `/context` shows this for Claude Code only; OpenCode closed the request as
+[not planned](https://github.com/anomalyco/opencode/issues/11995).
+
+## Demo
+
+![upfront measuring a demo project with three official MCP servers](https://raw.githubusercontent.com/thanatchon36/upfront/main/docs/demo.gif)
+
+```console
+$ uv run upfront examples/demo --yes --top 2      # in a clone of this repository
+upfront 0.1.0 · examples/demo · tokens o200k_base
+
+claude-code                                      ≈ 6,786  before your first prompt
+  mcp filesystem (14 tools, project)             ≈ 2,751
+      read_media_file                              ≈ 285
+      read_text_file                               ≈ 251
+  mcp memory (9 tools, project)                  ≈ 2,365
+      create_entities                              ≈ 349
+      search_nodes                                 ≈ 320
+  mcp everything (13 tools, project)             ≈ 1,602
+      gzip-file-as-resource                        ≈ 239
+      get-structured-content                       ≈ 186
+  skills (2, name + description)                    ≈ 33  bodies ≈ 48 load on demand
+  CLAUDE.md                                         ≈ 35
+...
+compatibility
+  error   codex       issue-scenarios.files.read: 'files.read' (10 chars) is not a valid OpenAI function name
+          [openai-tool-name] https://github.com/openai/openai-python/blob/main/src/openai/types/shared_params/function_definition.py
+```
+
+The demo's servers replay `tools/list` snapshots of the official
+[filesystem, memory and everything](https://github.com/modelcontextprotocol/servers) reference
+servers (1.0.0), so the numbers above are what those servers really cost.
+
+## Install
+
+```bash
+uvx --from git+https://github.com/thanatchon36/upfront upfront    # run from your project, no install
+pip install upfront                                               # once v0.1.0 is on PyPI
+```
+
+Python 3.11+. Then, in a project:
+
+```bash
+upfront          # skills, instruction files and the list of servers; starts nothing
+upfront --yes    # also start/connect to each MCP server and count its tools
+```
+
+## Features
+
+- **Four harnesses, both scopes.** Reads Claude Code, Codex, Gemini CLI and OpenCode configs from the project and your home directory, including `${VAR:-default}` expansion and JSONC.
+- **Real tool lists.** Talks to every stdio, Streamable HTTP and SSE server with the official MCP SDK, follows pagination, and reports failures (missing command, timeout, "auth required") per server instead of crashing.
+- **Where the tokens go.** Per server and per tool, skill metadata separately from skill bodies, and every instruction file.
+- **Compatibility checks with sources.** Tool names against OpenAI, Anthropic and Gemini rules, `$ref` parameters in Claude Code, non-standard formats in OpenCode, and Codex's skills budget. Every finding links the documentation or open issue it comes from.
+- **CI-friendly.** `--json`, `--budget N` and `--strict` exit codes, and `--tools-file` to check a saved `tools/list` without starting anything.
+- **Safe by default.** Nothing is launched without consent: it asks in a terminal and needs `--yes` elsewhere. It only ever calls `tools/list`.
+
+## How it compares
+
+| | upfront | Claude Code [`/context`](https://code.claude.com/docs/en/commands) | [mcp-assert](https://github.com/blackwell-systems/mcp-assert) | [ccusage](https://github.com/ccusage/ccusage) |
+|---|---|---|---|---|
+| Up-front cost of MCP tools, skills, instruction files | yes, per harness | yes, Claude Code only | no | no |
+| Works for Codex, Gemini CLI, OpenCode | yes | no | n/a | n/a |
+| Per-client schema compatibility | yes, 6 sourced rules | no | no; 24 usability lint rules (descriptions, nesting) | no |
+| Tests tool *behaviour* | no | no | yes (assertions, fuzzing) | no |
+| Actual spend from past sessions | no | `/usage` | no | yes |
+
+Use `/context` inside Claude Code, mcp-assert to test what your tools do, and
+ccusage to see what you've already spent. upfront answers "what will each agent load, and what
+breaks where" before you start.
+
+## How it works
+
+1. **Discover**: parse each harness's documented config files ([concepts](https://github.com/thanatchon36/upfront/blob/main/docs/concepts.md#where-upfront-looks)).
+2. **Fetch**: with consent, start each distinct server once (from the project directory, like the agent) and page through `tools/list`.
+3. **Count**: tokenize each tool's wire JSON with `o200k_base`; skill metadata and bodies separately; instruction files whole.
+4. **Check**: run the per-client rules ([table](https://github.com/thanatchon36/upfront/blob/main/docs/api.md#compatibility-rules)).
+
+More: [quickstart](https://github.com/thanatchon36/upfront/blob/main/docs/quickstart.md) · [concepts](https://github.com/thanatchon36/upfront/blob/main/docs/concepts.md) · [FAQ](https://github.com/thanatchon36/upfront/blob/main/docs/faq.md) · [API](https://github.com/thanatchon36/upfront/blob/main/docs/api.md) · [decisions](https://github.com/thanatchon36/upfront/blob/main/docs/decisions/)
+
+## Limitations
+
+- **Estimates.** One tokenizer for every model; vendors' counts differ, and clients add their own framing around tools ([ADR-0003](https://github.com/thanatchon36/upfront/blob/main/docs/decisions/ADR-0003-tokenizer.md)).
+- **Not the vendor's system prompt.** Only what you add is measured.
+- **Lazy loading isn't modelled.** Claude Code's tool search and OpenCode's lazy MCP loading defer some definitions; upfront reports their full cost.
+- **No OAuth.** Remote servers that need a login show "auth required; not measured". Headers from your config are sent; OAuth flows are not run.
+- **Root-level instruction files only**, and only the four CLI harnesses above (no Cursor or Windsurf yet).
+- **Codex's 2% skills budget** depends on the model's window; upfront checks the documented 8,000-character fallback.
+
+## Roadmap
+
+- **v0.2**: exact counts via vendor token-count APIs (opt-in), a `--fix` proxy that rewrites schemas per client, Cursor and Windsurf configs.
+- **v0.3**: `upfront diff` between git refs for MCP server pull requests, and a GitHub Action.
+
+## Contributing
+
+Bug reports with a config that reproduces the problem help most. See
+[CONTRIBUTING.md](https://github.com/thanatchon36/upfront/blob/main/CONTRIBUTING.md); compatibility rules need a public source.
+
+## License
+
+[MIT](https://github.com/thanatchon36/upfront/blob/main/LICENSE)

upfront-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+upfront/__init__.py,sha256=DIdriHrfoums1yKsz8wlZ4JzbH84o4ydCZGHuymxB8g,231
+upfront/cli.py,sha256=Q5Fr2Q8OYp0pMSBIZyYJu4nQFEY5MY6PmY_BXLqWRBQ,5829
+upfront/compat.py,sha256=e-NsALUMWWmPgPIQpfZ9lLjtVM8A8yZdwIIxB3ZNSIQ,7144
+upfront/discover.py,sha256=qLiNWhyKyxHkvmNxHHmIrOSinCqm_AEYMmY69RMjVOU,15614
+upfront/fetch.py,sha256=Zfof2euItVMzOyMyrvce60yNsaKf8tz268yaJeSh6Q8,4738
+upfront/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+upfront/report.py,sha256=yMLd8ezWFvl_dJQiXSUq4bg75AiPtAz6VQEC_-Ukw0M,5416
+upfront/tokens.py,sha256=Z9yVgrxrmSiIN7s-e7eGntkcjm66Dch8AgBdc8_m4Io,1564
+upfront-0.1.0.dist-info/METADATA,sha256=GgZOw16IuJ7myNoTBnJzzL3Bd_z5xqFYSdPm-bKA79M,8937
+upfront-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+upfront-0.1.0.dist-info/entry_points.txt,sha256=qK-OiuI2cduITedrQwzCMCxrfCtGatZDV-hYXLsFX6I,44
+upfront-0.1.0.dist-info/licenses/LICENSE,sha256=Jtf260CBjZOjOV_B54IS4Gyo0G-FpRGipO7oXBPfqYA,1067
+upfront-0.1.0.dist-info/RECORD,,

upfront-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

upfront-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+upfront = upfront.cli:app

upfront-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thanatchon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.