chipfoundry-cli 2.3.19__tar.gz → 2.4.0__tar.gz

{chipfoundry_cli-2.3.19 → chipfoundry_cli-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: chipfoundry-cli
-Version: 2.3.19
+Version: 2.4.0
 Summary: CLI tool to automate ChipFoundry project submission to SFTP server
 Home-page: https://chipfoundry.io
 License: Apache-2.0

chipfoundry_cli-2.4.0/chipfoundry_cli/check_refs.py

@@ -0,0 +1,42 @@
+"""Known cf-precheck check names with display metadata.
+
+Must stay in sync with cf-precheck's ``ALL_CHECKS`` ordering
+(see ``cf-precheck/src/cf_precheck/check_manager.py``). The backend mirrors
+the ref keys in ``chipignite-backend-services/src/precheck_service/check_refs.py``.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+
+class PrecheckCheck(NamedTuple):
+    ref: str
+    surname: str
+    optional: bool
+
+
+PRECHECK_CHECKS: tuple[PrecheckCheck, ...] = (
+    PrecheckCheck("topcell_check", "Top Cell", False),
+    PrecheckCheck("gpio_defines", "GPIO Defines", False),
+    PrecheckCheck("pdnmulti", "PDN Multi", False),
+    PrecheckCheck("metalcheck", "Metal Check", False),
+    PrecheckCheck("xor", "XOR", False),
+    PrecheckCheck("magic_drc", "Magic DRC", True),
+    PrecheckCheck("klayout_feol", "Klayout FEOL", False),
+    PrecheckCheck("klayout_beol", "Klayout BEOL", False),
+    PrecheckCheck("klayout_offgrid", "Klayout Offgrid", False),
+    PrecheckCheck("klayout_met_min_ca_density", "Klayout Metal Density", False),
+    PrecheckCheck(
+        "klayout_pin_label_purposes_overlapping_drawing",
+        "Klayout Pin Label",
+        False,
+    ),
+    PrecheckCheck("klayout_zeroarea", "Klayout ZeroArea", False),
+    PrecheckCheck("spike_check", "Spike Check", False),
+    PrecheckCheck("illegal_cellname_check", "Illegal Cellname", False),
+    PrecheckCheck("lvs", "LVS", False),
+    PrecheckCheck("oeb", "OEB", False),
+)
+
+PRECHECK_CHECK_REFS: frozenset[str] = frozenset(c.ref for c in PRECHECK_CHECKS)

{chipfoundry_cli-2.3.19 → chipfoundry_cli-2.4.0}/chipfoundry_cli/main.py

@@ -1,7 +1,9 @@
 import click
 import getpass
 from typing import Optional, List
+from chipfoundry_cli.check_refs import PRECHECK_CHECKS
 from chipfoundry_cli.remote_precheck_git import RemotePrecheckGitError, verify_remote_precheck_repo
+from chipfoundry_cli.version_check import maybe_warn_outdated
 from chipfoundry_cli.utils import (
     collect_project_files, ensure_cf_directory, update_or_create_project_json,
     sftp_connect, upload_with_progress, sftp_ensure_dirs, sftp_download_recursive,
@@ -174,7 +176,16 @@ def check_project_initialized(project_root_path: Path, command_name: str, dry_ru
 @click.group(help="ChipFoundry CLI: Automate project submission and management.")
 @click.version_option(importlib.metadata.version("chipfoundry-cli"), "-v", "--version", message="%(version)s")
 def main():
-    pass
+    # Best-effort upgrade check. Cached on disk for CACHE_TTL_SECONDS and
+    # guarded by a short timeout so it never slows down a command. Runs
+    # only when a subcommand was dispatched — `cf --version` / `cf --help`
+    # exit before this callback fires.
+    try:
+        current = importlib.metadata.version("chipfoundry-cli")
+        maybe_warn_outdated(current, _get_api_url(), console, user_agent=_cf_user_agent())
+    except Exception:
+        # Never let a version-check issue break the actual command.
+        pass
 
 @main.command('config')
 def config_cmd():
@@ -3553,11 +3564,62 @@ def _upload_precheck_results(project_json_path: Path):
         console.print("[yellow]⚠ Precheck results could not be synced to platform[/yellow]")
 
 
-@main.command('precheck')
+def _print_precheck_checks() -> None:
+    """Print the list of available precheck checks as a table."""
+    table = Table(title="Available cf-precheck checks", show_lines=False)
+    table.add_column("Ref", style="cyan", no_wrap=True)
+    table.add_column("Name", style="white")
+    table.add_column("Default", style="green")
+    for c in PRECHECK_CHECKS:
+        default = "opt-in" if c.optional else "on"
+        table.add_row(c.ref, c.surname, default)
+    console.print(table)
+    console.print(
+        "\n[dim]Use [bold]--checks REF[/bold] to run only specific checks, "
+        "[bold]--skip-checks REF[/bold] to skip, or [bold]--magic-drc[/bold] "
+        "to include the optional Magic DRC check.[/dim]"
+    )
+
+
+def _build_precheck_help() -> str:
+    """Build the --help text, including the list of available checks."""
+    lines = [
+        "Run precheck validation on the project.",
+        "",
+        "This runs the cf-precheck tool to validate your design before submission.",
+        "",
+        "\b",
+        "Examples:",
+        "    cf precheck                              # Run all checks",
+        "    cf precheck --list-checks                # List available checks and exit",
+        "    cf precheck --skip-checks lvs            # Skip LVS check",
+        "    cf precheck --magic-drc                  # Include optional Magic DRC",
+        "    cf precheck --checks topcell_check       # Run specific checks only",
+        "    cf precheck --remote                     # Queue on platform; exit when accepted",
+        "    cf precheck --remote --poll              # Wait and stream progress",
+        "    cf precheck --remote --poll --wait-timeout 0    # Poll until done (no time limit)",
+        "",
+        "\b",
+        "Available checks (pass to --checks / --skip-checks):",
+    ]
+    for c in PRECHECK_CHECKS:
+        suffix = "  (optional; opt in via --magic-drc)" if c.optional else ""
+        lines.append(f"    {c.ref}{suffix}")
+    lines += [
+        "",
+        "Remote precheck requires your local HEAD to match origin for --git-ref, and",
+        "precheck inputs (wrapper GDS, verilog/rtl/user_defines.v when the GPIO check",
+        "runs, and tracked .cf/project.json) to match that commit.",
+    ]
+    return "\n".join(lines)
+
+
+@main.command('precheck', help=_build_precheck_help())
 @click.option('--project-root', type=click.Path(exists=True, file_okay=False), help='Path to the project directory (defaults to current directory)')
-@click.option('--skip-checks', multiple=True, help='Checks to skip (can be specified multiple times)')
+@click.option('--skip-checks', multiple=True, help='Checks to skip (repeatable). See --list-checks for valid refs.')
 @click.option('--magic-drc', is_flag=True, help='Include Magic DRC check (optional, off by default)')
-@click.option('--checks', multiple=True, help='Specific checks to run (can be specified multiple times)')
+@click.option('--checks', multiple=True, help='Specific checks to run (repeatable). See --list-checks for valid refs.')
+@click.option('--list-checks', 'list_checks', is_flag=True, help='List the available precheck checks and exit.')
 @click.option('--dry-run', is_flag=True, help='Show the command without running')
 @click.option('--remote', is_flag=True, help='Queue precheck on the ChipFoundry platform (requires cf login + linked project)')
 @click.option(
@@ -3573,25 +3635,10 @@ def _upload_precheck_results(project_json_path: Path):
     show_default=True,
     help='With --remote --poll: max seconds to wait (0 = no limit). Ignored without --poll.',
 )
-def precheck(project_root, skip_checks, magic_drc, checks, dry_run, remote, poll, git_ref, wait_timeout):
-    """Run precheck validation on the project.
-    
-    This runs the cf-precheck tool to validate your design before
-    submission.
-    
-    Examples:
-        cf precheck                              # Run all checks
-        cf precheck --skip-checks lvs            # Skip LVS check
-        cf precheck --magic-drc                  # Include optional Magic DRC
-        cf precheck --checks topcell_check       # Run specific checks only
-        cf precheck --remote                     # Queue on platform; exit when accepted
-        cf precheck --remote --poll              # Wait and stream progress
-        cf precheck --remote --poll --wait-timeout 0    # Poll until done (no time limit)
-
-    Remote precheck requires your local HEAD to match origin for --git-ref, and precheck
-    inputs (wrapper GDS, verilog/rtl/user_defines.v when the GPIO check runs, and tracked
-    .cf/project.json) to match that commit.
-    """
+def precheck(project_root, skip_checks, magic_drc, checks, list_checks, dry_run, remote, poll, git_ref, wait_timeout):
+    if list_checks:
+        _print_precheck_checks()
+        return
     cwd_root, _ = get_project_json_from_cwd()
     if not project_root and cwd_root:
         project_root = cwd_root
@@ -3659,7 +3706,10 @@ def precheck(project_root, skip_checks, magic_drc, checks, dry_run, remote, poll
         api_url = _get_api_url()
         client = httpx_remote.Client(
             base_url=f"{api_url}/api/v1",
-            headers={'Authorization': f'Bearer {api_key}'},
+            headers={
+                'Authorization': f'Bearer {api_key}',
+                'User-Agent': _cf_user_agent(),
+            },
             timeout=120.0,
         )
         try:
@@ -4174,6 +4224,24 @@ DEFAULT_API_URL = 'https://api.chipfoundry.io'
 PORTAL_BASE_URL = 'https://platform.chipfoundry.io'
 
 
+def _cf_user_agent() -> str:
+    """User-Agent string for platform requests.
+
+    Format: ``chipfoundry-cli/<cli-version> python/<py-version> <platform>``.
+    Lets the backend track which CLI versions are in the wild without a
+    dedicated telemetry endpoint.
+    """
+    import platform as _platform
+
+    try:
+        cli_version = importlib.metadata.version("chipfoundry-cli")
+    except importlib.metadata.PackageNotFoundError:
+        cli_version = "unknown"
+    py = _platform.python_version()
+    system = f"{_platform.system().lower()}-{_platform.machine().lower()}"
+    return f"chipfoundry-cli/{cli_version} python/{py} {system}"
+
+
 def _get_api_url() -> str:
     config = load_user_config()
     return config.get('api_url', DEFAULT_API_URL)
@@ -4199,7 +4267,10 @@ def _api_client():
     api_url = _get_api_url()
     client = httpx.Client(
         base_url=f"{api_url}/api/v1",
-        headers={'Authorization': f'Bearer {api_key}'},
+        headers={
+            'Authorization': f'Bearer {api_key}',
+            'User-Agent': _cf_user_agent(),
+        },
         timeout=15,
     )
     return client, api_url
@@ -4435,7 +4506,11 @@ def login_cmd(test):
     console.print(f"Opening browser to authenticate with [bold]{api_url}[/bold]...\n")
 
     try:
-        resp = httpx.post(f"{api_url}/api/v1/auth/cli/sessions", timeout=10)
+        resp = httpx.post(
+            f"{api_url}/api/v1/auth/cli/sessions",
+            headers={'User-Agent': _cf_user_agent()},
+            timeout=10,
+        )
         resp.raise_for_status()
         data = resp.json()
     except httpx.HTTPError as e:
@@ -4457,7 +4532,11 @@ def login_cmd(test):
     for _ in range(max_polls):
         time.sleep(poll_interval)
         try:
-            poll_resp = httpx.get(poll_url, timeout=10)
+            poll_resp = httpx.get(
+                poll_url,
+                headers={'User-Agent': _cf_user_agent()},
+                timeout=10,
+            )
             poll_resp.raise_for_status()
             poll_data = poll_resp.json()
         except httpx.HTTPError:
@@ -4528,7 +4607,10 @@ def whoami_cmd():
     try:
         resp = httpx.get(
             f"{api_url}/api/v1/auth/cli/whoami",
-            headers={'Authorization': f'Bearer {api_key}'},
+            headers={
+                'Authorization': f'Bearer {api_key}',
+                'User-Agent': _cf_user_agent(),
+            },
             timeout=10,
         )
         if resp.status_code == 401:

chipfoundry_cli-2.4.0/chipfoundry_cli/version_check.py

@@ -0,0 +1,204 @@
+"""Client-side upgrade check for the ``cf`` CLI.
+
+Polls ``GET /api/v1/cli/version`` on the public API with a short timeout
+and caches the response on disk so we only hit the network a few times
+per day per user. Prints a dim warning if the installed version is
+behind the latest published release. All errors are swallowed — a
+failed check must never block or delay a normal command.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from rich.console import Console
+
+from chipfoundry_cli.utils import get_config_path
+
+
+CACHE_FILENAME = "version_check.json"
+CACHE_TTL_SECONDS = 6 * 60 * 60  # 6 hours
+NETWORK_TIMEOUT_SECONDS = 1.5
+ENDPOINT_PATH = "/api/v1/cli/version"
+ENV_DISABLE = "CF_SKIP_VERSION_CHECK"
+
+
+@dataclass(frozen=True)
+class VersionInfo:
+    latest: str
+    minimum_supported: str
+    upgrade_command: str
+    release_notes_url: str
+
+
+def _cache_path() -> Path:
+    return get_config_path().parent / CACHE_FILENAME
+
+
+def _parse_semver(version: str) -> tuple[int, ...]:
+    """Parse ``X.Y.Z`` (optionally with pre-release suffix) into a tuple.
+
+    Unknown or non-numeric components are treated as 0 so a malformed
+    version never crashes the CLI. This is intentionally lightweight —
+    we don't pull in ``packaging`` just for this.
+    """
+    cleaned = version.strip().lstrip("v")
+    # Drop any pre-release / build-metadata suffix (e.g. ``1.2.3-rc1+sha``).
+    for sep in ("-", "+"):
+        if sep in cleaned:
+            cleaned = cleaned.split(sep, 1)[0]
+    parts: list[int] = []
+    for piece in cleaned.split("."):
+        try:
+            parts.append(int(piece))
+        except ValueError:
+            parts.append(0)
+    while len(parts) < 3:
+        parts.append(0)
+    return tuple(parts[:3])
+
+
+def _is_older(current: str, target: str) -> bool:
+    """Return True if ``current`` is strictly older than ``target``."""
+    return _parse_semver(current) < _parse_semver(target)
+
+
+def _read_cache() -> Optional[dict]:
+    path = _cache_path()
+    if not path.exists():
+        return None
+    try:
+        with open(path, "r") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    ts = data.get("fetched_at")
+    if not isinstance(ts, (int, float)):
+        return None
+    if (time.time() - ts) > CACHE_TTL_SECONDS:
+        return None
+    return data
+
+
+def _write_cache(payload: dict) -> None:
+    path = _cache_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".json.tmp")
+        with open(tmp, "w") as f:
+            json.dump(payload, f)
+        tmp.replace(path)
+    except OSError:
+        # Cache is an optimization; never fail the command because we
+        # couldn't write it.
+        pass
+
+
+def _fetch_latest(api_url: str, user_agent: Optional[str] = None) -> Optional[VersionInfo]:
+    """Hit the platform endpoint. Returns None on any failure."""
+    import httpx
+
+    url = f"{api_url.rstrip('/')}{ENDPOINT_PATH}"
+    headers = {"User-Agent": user_agent} if user_agent else {}
+    try:
+        resp = httpx.get(url, headers=headers, timeout=NETWORK_TIMEOUT_SECONDS)
+        resp.raise_for_status()
+        body = resp.json()
+    except Exception:
+        return None
+    try:
+        return VersionInfo(
+            latest=str(body["latest"]),
+            minimum_supported=str(body["minimum_supported"]),
+            upgrade_command=str(body["upgrade_command"]),
+            release_notes_url=str(body.get("release_notes_url", "")),
+        )
+    except (KeyError, TypeError):
+        return None
+
+
+def _load_or_fetch(api_url: str, user_agent: Optional[str] = None) -> Optional[VersionInfo]:
+    cached = _read_cache()
+    if cached is not None and "info" in cached:
+        info = cached["info"]
+        try:
+            return VersionInfo(
+                latest=str(info["latest"]),
+                minimum_supported=str(info["minimum_supported"]),
+                upgrade_command=str(info["upgrade_command"]),
+                release_notes_url=str(info.get("release_notes_url", "")),
+            )
+        except (KeyError, TypeError):
+            pass
+    fresh = _fetch_latest(api_url, user_agent=user_agent)
+    if fresh is not None:
+        _write_cache(
+            {
+                "fetched_at": time.time(),
+                "info": {
+                    "latest": fresh.latest,
+                    "minimum_supported": fresh.minimum_supported,
+                    "upgrade_command": fresh.upgrade_command,
+                    "release_notes_url": fresh.release_notes_url,
+                },
+            }
+        )
+    return fresh
+
+
+def maybe_warn_outdated(
+    current_version: str,
+    api_url: str,
+    console: Console,
+    user_agent: Optional[str] = None,
+) -> None:
+    """Print a warning if the installed CLI is behind.
+
+    Two severity tiers:
+
+    * **Below ``minimum_supported``** → prominent red warning. The
+      server will already reject these requests with HTTP 426 (see
+      :mod:`src.cli_version_service.hard_floor`); we surface the
+      upgrade instruction here so users learn *why* before they see the
+      error on their next real command.
+    * **Behind ``latest`` but at/above minimum** → dim yellow tip.
+      Purely informational.
+
+    Never raises.
+    """
+    if os.environ.get(ENV_DISABLE, "").strip() not in ("", "0", "false", "False"):
+        return
+    try:
+        info = _load_or_fetch(api_url, user_agent=user_agent)
+    except Exception:
+        return
+    if info is None:
+        return
+
+    notes = (
+        f" ({info.release_notes_url})" if info.release_notes_url else ""
+    )
+
+    if _is_older(current_version, info.minimum_supported):
+        console.print(
+            f"[red]✗ cf {current_version} is below the minimum supported "
+            f"version ({info.minimum_supported}).[/red] The platform will "
+            f"reject API calls from this install.\n"
+            f"  Upgrade now: [cyan]{info.upgrade_command}[/cyan]{notes}"
+        )
+        return
+
+    if _is_older(current_version, info.latest):
+        console.print(
+            f"[yellow]⚠[/yellow] A newer [bold]cf[/bold] is available: "
+            f"[bold]{info.latest}[/bold] (you have {current_version}).\n"
+            f"  Upgrade: [cyan]{info.upgrade_command}[/cyan]{notes}",
+            style="dim",
+        )

{chipfoundry_cli-2.3.19 → chipfoundry_cli-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "chipfoundry-cli"
-version = "2.3.19"
+version = "2.4.0"
 description = "CLI tool to automate ChipFoundry project submission to SFTP server"
 authors = ["ChipFoundry <marwan.abbas@chipfoundry.io>"]
 readme = "README.md"