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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: chipfoundry-cli
-Version: 2.3.19
+Version: 2.4.4
 Summary: CLI tool to automate ChipFoundry project submission to SFTP server
 Home-page: https://chipfoundry.io
 License: Apache-2.0
@@ -603,6 +603,7 @@ cf push [OPTIONS]
 - `--sftp-username`: Override configured username (SFTP mode only)
 - `--sftp-key`: Override configured key path (SFTP mode only)
 - `--remote`: HTTPS-only upload via the ChipFoundry GitHub App (no SFTP). Use this when port 22 is blocked by your corporate firewall.
+- `--https`: HTTPS-only direct upload to AWS S3 (no SFTP, no GitHub). Use this when both SFTP and GitHub are blocked by your corporate firewall.
 
 **SFTP mode (default):**
 1. Verifies the project is linked to the platform and you are logged in
@@ -636,6 +637,34 @@ What happens:
 > network, run `cf push --remote` instead. No VPN required — just outbound
 > HTTPS and a GitHub repo linked to the project.
 
+**HTTPS direct mode — `cf push --https`:**
+
+Firewall-friendliest fallback: no SFTP, no GitHub, no Git at all. The CLI
+uploads your push-critical files directly to an AWS S3 staging bucket over
+HTTPS using short-lived pre-signed PUT URLs, then the platform stages the
+objects onto your SFTP landing zone. Use this when your network blocks
+both port 22 and GitHub.
+
+Preconditions:
+- Project is linked to the platform (`cf init` or `cf link`) and you are logged in.
+- Wrapper GDS exists locally under `gds/` (one of `user_project_wrapper.gds[.gz]`,
+  `user_analog_project_wrapper.gds[.gz]`, `openframe_project_wrapper.gds[.gz]`).
+- For non-openframe projects, `verilog/rtl/user_defines.v` is also uploaded when present.
+- Outbound HTTPS to `*.s3.us-east-2.amazonaws.com` is allowed.
+
+What happens:
+1. `cf push --https` picks the wrapper GDS (and `user_defines.v` if applicable) and hashes each file with SHA-256 locally.
+2. Platform returns one pre-signed PUT URL per file; the CLI PUTs each file directly to S3 over HTTPS.
+3. Platform stages the objects onto your SFTP landing zone, re-verifying SHA-256 byte-for-byte and synthesizing `.cf/project.json` from the authoritative platform data.
+4. Staged S3 objects are deleted on success; any leftovers are expired by the bucket lifecycle after 7 days.
+5. `--submit` submits for review on success.
+
+> [!TIP]
+> Try modes in this order: `cf push` → `cf push --remote` → `cf push --https`.
+> The SFTP mode is fastest when unrestricted, `--remote` is the best HTTPS
+> option when you already keep the project on GitHub, and `--https` is the
+> "direct upload" escape hatch that works even with no Git.
+
 **GDS File Handling:**
 - **Both compressed (`.gz`) and uncompressed (`.gds`) files are supported**
 - **No automatic compression** - files are uploaded as-is

{chipfoundry_cli-2.3.19 → chipfoundry_cli-2.4.4}/README.md

@@ -577,6 +577,7 @@ cf push [OPTIONS]
 - `--sftp-username`: Override configured username (SFTP mode only)
 - `--sftp-key`: Override configured key path (SFTP mode only)
 - `--remote`: HTTPS-only upload via the ChipFoundry GitHub App (no SFTP). Use this when port 22 is blocked by your corporate firewall.
+- `--https`: HTTPS-only direct upload to AWS S3 (no SFTP, no GitHub). Use this when both SFTP and GitHub are blocked by your corporate firewall.
 
 **SFTP mode (default):**
 1. Verifies the project is linked to the platform and you are logged in
@@ -610,6 +611,34 @@ What happens:
 > network, run `cf push --remote` instead. No VPN required — just outbound
 > HTTPS and a GitHub repo linked to the project.
 
+**HTTPS direct mode — `cf push --https`:**
+
+Firewall-friendliest fallback: no SFTP, no GitHub, no Git at all. The CLI
+uploads your push-critical files directly to an AWS S3 staging bucket over
+HTTPS using short-lived pre-signed PUT URLs, then the platform stages the
+objects onto your SFTP landing zone. Use this when your network blocks
+both port 22 and GitHub.
+
+Preconditions:
+- Project is linked to the platform (`cf init` or `cf link`) and you are logged in.
+- Wrapper GDS exists locally under `gds/` (one of `user_project_wrapper.gds[.gz]`,
+  `user_analog_project_wrapper.gds[.gz]`, `openframe_project_wrapper.gds[.gz]`).
+- For non-openframe projects, `verilog/rtl/user_defines.v` is also uploaded when present.
+- Outbound HTTPS to `*.s3.us-east-2.amazonaws.com` is allowed.
+
+What happens:
+1. `cf push --https` picks the wrapper GDS (and `user_defines.v` if applicable) and hashes each file with SHA-256 locally.
+2. Platform returns one pre-signed PUT URL per file; the CLI PUTs each file directly to S3 over HTTPS.
+3. Platform stages the objects onto your SFTP landing zone, re-verifying SHA-256 byte-for-byte and synthesizing `.cf/project.json` from the authoritative platform data.
+4. Staged S3 objects are deleted on success; any leftovers are expired by the bucket lifecycle after 7 days.
+5. `--submit` submits for review on success.
+
+> [!TIP]
+> Try modes in this order: `cf push` → `cf push --remote` → `cf push --https`.
+> The SFTP mode is fastest when unrestricted, `--remote` is the best HTTPS
+> option when you already keep the project on GitHub, and `--https` is the
+> "direct upload" escape hatch that works even with no Git.
+
 **GDS File Handling:**
 - **Both compressed (`.gz`) and uncompressed (`.gds`) files are supported**
 - **No automatic compression** - files are uploaded as-is

{chipfoundry_cli-2.3.19 → chipfoundry_cli-2.4.4}/chipfoundry_cli/__init__.py

@@ -1,2 +1,2 @@
 """ChipFoundry CLI package: Automate project submission to SFTP."""
-__version__ = "2.3.2"
+__version__ = "2.4.1"

chipfoundry_cli-2.4.4/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.4}/chipfoundry_cli/main.py

@@ -1,7 +1,10 @@
 import click
 import getpass
-from typing import Optional, List
+import hashlib
+from typing import Optional, List, Tuple
+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 +177,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():
@@ -391,8 +403,13 @@ def init(project_root, shuttle, description):
     local_proj = local_data.get('project', {}) if isinstance(local_data, dict) else {}
 
     config = load_user_config()
+    api_key = config.get('api_key')
     username = config.get("sftp_username")
-    if not username:
+    # Try to refresh sftp_username from the platform, but don't block init on it.
+    # SFTP accounts are only auto-provisioned once a project deposit is paid/waived/
+    # sponsored and the user has an SSH key on their profile; init must work before
+    # that so users can configure locally and use `cf precheck` / `cf push --remote`.
+    if not username and api_key:
         try:
             me = _api_get("/auth/cli/whoami")
             username = me.get("sftp_username")
@@ -401,11 +418,10 @@ def init(project_root, shuttle, description):
                 save_user_config(config)
         except SystemExit:
             pass
-    if not username:
-        console.print("[bold red]No SFTP account linked to your platform account. Please run 'cf login' first.[/bold red]")
-        raise click.Abort()
-
-    api_key = config.get('api_key')
+    # Fall back to email (or 'unknown') purely as a label in .cf/project.json.
+    # This field is metadata only: SFTP routing uses the live session identity,
+    # and the backend stores cli_project_json as an opaque blob.
+    user_label = username or config.get("user_email") or "unknown"
     platform_id = local_proj.get('platform_project_id')
     platform_proj: Optional[dict] = None
     if platform_id and api_key:
@@ -458,7 +474,7 @@ def init(project_root, shuttle, description):
     proj = data.setdefault('project', {})
     proj['name'] = name
     proj['type'] = project_type
-    proj['user'] = username
+    proj['user'] = user_label
     proj.setdefault('version', local_proj.get('version') or "1")
     proj.setdefault('user_project_wrapper_hash', local_proj.get('user_project_wrapper_hash', ""))
     proj.setdefault('submission_state', local_proj.get('submission_state', "Draft"))
@@ -1557,6 +1573,263 @@ def _push_remote(project_root: Optional[str], project_name: Optional[str], dry_r
             console.print("[yellow]⚠ Submit failed — ensure the project has a name[/yellow]")
 
 
+def _sha256_file(path: Path) -> str:
+    """SHA-256 of a file streamed in 4 KiB chunks.
+
+    Must match the shuttle importer and the Lambda side so the server can
+    verify the upload byte-for-byte.
+    """
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(4096), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _collect_push_candidates(project_root: Path) -> List[Tuple[str, Path, int, str]]:
+    """Return [(rel_path, abs_path, size, kind)] for files the platform
+    accepts via --https.
+
+    Picks exactly one wrapper GDS (analog/digital/openframe) and, for
+    non-openframe projects, ``verilog/rtl/user_defines.v`` if it exists.
+    Raises FileNotFoundError if no wrapper is present or
+    ValueError if multiple are.
+    """
+    from chipfoundry_cli.utils import GDS_WRAPPER_BASES, GDS_WRAPPER_SUFFIXES, USER_DEFINES_REL
+
+    hits: List[Tuple[str, str]] = []
+    for kind, base in GDS_WRAPPER_BASES:
+        for suf in GDS_WRAPPER_SUFFIXES:
+            rel = base + suf
+            if (project_root / rel).is_file():
+                hits.append((kind, rel))
+                break
+    if not hits:
+        raise FileNotFoundError(
+            "No wrapper GDS found (expected one of gds/user_project_wrapper.gds[.gz], "
+            "gds/user_analog_project_wrapper.gds[.gz], "
+            "gds/openframe_project_wrapper.gds[.gz])."
+        )
+    if len(hits) > 1:
+        paths = ", ".join(h[1] for h in hits)
+        raise ValueError(
+            f"Multiple wrapper GDS layouts present ({paths}). Keep only one."
+        )
+
+    kind, wrapper_rel = hits[0]
+    abs_wrapper = project_root / wrapper_rel
+    results: List[Tuple[str, Path, int, str]] = [
+        (wrapper_rel, abs_wrapper, abs_wrapper.stat().st_size, "wrapper")
+    ]
+
+    if kind != "openframe":
+        ud = project_root / USER_DEFINES_REL
+        if ud.is_file():
+            results.append((USER_DEFINES_REL, ud, ud.stat().st_size, "aux"))
+
+    return results
+
+
+def _push_https(project_root: Optional[str], project_name: Optional[str], dry_run: bool, submit: bool) -> None:
+    """Push project files to the platform by uploading directly to S3 over HTTPS.
+
+    Use case: customers whose network blocks BOTH SFTP (port 22) and
+    GitHub, so they cannot use `cf push` or `cf push --remote`. They can
+    still reach AWS S3 over HTTPS, which is what the backend hands them
+    via pre-signed PUT URLs.
+
+    No Git involvement at all — the CLI hashes the local files, the
+    backend returns pre-signed URLs, the CLI PUTs directly to S3, and
+    the platform stages the objects onto EFS with the same synthesized
+    .cf/project.json the --remote flow produces.
+    """
+    cwd_root, cwd_project_name = get_project_json_from_cwd()
+    if not project_root and cwd_root:
+        project_root = cwd_root
+    if not project_name and cwd_project_name:
+        project_name = cwd_project_name
+    if not project_root:
+        console.print(
+            "[red]No project root specified and no .cf/project.json found in current directory.[/red]"
+        )
+        console.print("Provide --project-root or run from a linked project.")
+        raise click.Abort()
+    project_root = str(Path(project_root).resolve())
+
+    platform_id = _load_project_platform_id(project_root)
+    if not platform_id:
+        console.print("[red]Project is not linked to the platform.[/red]")
+        console.print("Run [bold]cf link[/bold] to connect this project, or [bold]cf init[/bold] to create a new one.")
+        raise click.Abort()
+
+    config = load_user_config()
+    if not config.get("api_key"):
+        console.print("[red]Not logged in.[/red] Run [bold]cf login[/bold] before using --https.")
+        raise click.Abort()
+
+    try:
+        candidates = _collect_push_candidates(Path(project_root))
+    except FileNotFoundError as e:
+        console.print(f"[red]HTTPS push not ready:[/red] {e}")
+        raise click.Abort()
+    except ValueError as e:
+        console.print(f"[red]HTTPS push not ready:[/red] {e}")
+        raise click.Abort()
+
+    final_project_name = project_name or Path(project_root).name
+
+    total_bytes = sum(c[2] for c in candidates)
+    mb = total_bytes / (1024 * 1024)
+    console.print(
+        f"[green]✓ Ready to upload[/green] [cyan]{len(candidates)}[/cyan] file(s) "
+        f"([cyan]{mb:.1f} MiB[/cyan] total) to the platform over HTTPS."
+    )
+
+    if dry_run:
+        console.print("\n[bold]HTTPS push preview:[/bold]")
+        console.print(f"  Platform project: {platform_id}")
+        console.print(f"  Project name:     {final_project_name}")
+        for rel, abs_path, size, _ in candidates:
+            console.print(f"  • {rel} ({size / (1024 * 1024):.1f} MiB)")
+        console.print("  (no files uploaded — dry run)")
+        return
+
+    console.print("[dim]Hashing files locally…[/dim]")
+    hashed: List[dict] = []
+    for rel, abs_path, size, _ in candidates:
+        digest = _sha256_file(abs_path)
+        hashed.append({"rel_path": rel, "size": size, "sha256": digest})
+        console.print(f"  [dim]sha256[/dim] {digest[:16]}…  {rel}")
+
+    console.print("Requesting upload slots from the platform…")
+    try:
+        init_resp = _api_post(
+            f"/projects/{platform_id}/https-push/init",
+            {"project_name": final_project_name, "files": hashed},
+            timeout=60.0,
+        )
+    except SystemExit:
+        raise click.Abort()
+
+    upload_id = init_resp.get("upload_id") or ""
+    put_targets = {f["rel_path"]: f["put_url"] for f in (init_resp.get("files") or [])}
+    if not upload_id or len(put_targets) != len(candidates):
+        console.print("[red]✗ Platform did not return upload slots for every file.[/red]")
+        raise click.Abort()
+
+    console.print(
+        f"[dim]Upload id [bold]{upload_id[:8]}[/bold] — uploading to "
+        f"{init_resp.get('bucket')} (HTTPS, {init_resp.get('expires_in', 3600)}s TTL)…[/dim]"
+    )
+
+    # Per-file single PUT. We reuse one httpx client with a generous
+    # timeout; the signed URL carries auth so no headers besides
+    # x-amz-server-side-encryption are required.
+    #
+    # We stream the body with a generator instead of passing the file
+    # directly so we can drive a rich progress bar (matches the UX of
+    # the SFTP push path in utils.upload_with_progress). Content-Length
+    # is set explicitly so S3 doesn't fall back to chunked encoding,
+    # which pre-signed PUTs don't allow.
+    import httpx
+    from rich.progress import DownloadColumn, TransferSpeedColumn
+
+    put_timeout = httpx.Timeout(connect=10.0, read=1800.0, write=1800.0, pool=30.0)
+    chunk_size = 1024 * 1024  # 1 MiB — big enough to keep overhead low, small enough for smooth bar updates
+    with httpx.Client(timeout=put_timeout) as put_client:
+        for rel, abs_path, size, _ in candidates:
+            url = put_targets[rel]
+            with Progress(
+                TextColumn("  [cyan]↑[/cyan] [progress.description]{task.description}"),
+                BarColumn(),
+                TaskProgressColumn(),
+                DownloadColumn(),
+                TransferSpeedColumn(),
+                TimeElapsedColumn(),
+                console=console,
+                transient=False,
+            ) as progress:
+                task = progress.add_task(rel, total=max(size, 1))
+                if size == 0:
+                    # httpx won't call our generator for an empty body;
+                    # advance the bar manually so the user sees it complete.
+                    progress.update(task, completed=1)
+
+                def _body_iter(path=abs_path, tid=task, prog=progress):
+                    with open(path, "rb") as fh:
+                        while True:
+                            buf = fh.read(chunk_size)
+                            if not buf:
+                                break
+                            prog.update(tid, advance=len(buf))
+                            yield buf
+
+                try:
+                    resp = put_client.put(
+                        url,
+                        content=_body_iter() if size > 0 else b"",
+                        headers={
+                            "Content-Type": "application/octet-stream",
+                            "Content-Length": str(size),
+                            "x-amz-server-side-encryption": "AES256",
+                        },
+                    )
+                    if resp.status_code >= 300:
+                        body = resp.text[:300]
+                        console.print(
+                            f"[red]✗ Upload of {rel} failed: HTTP {resp.status_code} — {body}[/red]"
+                        )
+                        raise click.Abort()
+                except click.Abort:
+                    raise
+                except Exception as e:
+                    console.print(f"[red]✗ Upload of {rel} failed: {type(e).__name__}: {e}[/red]")
+                    raise click.Abort()
+
+    console.print("[green]✓ All files uploaded. Asking platform to stage them on EFS…[/green]")
+    try:
+        complete_resp = _api_post(
+            f"/projects/{platform_id}/https-push/complete",
+            {"upload_id": upload_id, "project_name": final_project_name},
+            timeout=600.0,
+        )
+    except SystemExit:
+        raise click.Abort()
+
+    landed = complete_resp.get("landed") or []
+    if landed:
+        console.print("[green]✓ Files staged on the platform:[/green]")
+        for rel in landed:
+            console.print(f"  • {rel}")
+    else:
+        console.print("[yellow]⚠ Platform accepted the request but did not report any landed files.[/yellow]")
+
+    try:
+        with open(Path(project_root) / ".cf" / "project.json", "r") as f:
+            pj = json.load(f)
+        _api_put(
+            f"/projects/{platform_id}",
+            {"cli_project_json": _slim_project_json(pj), "cli_sync_source": "push"},
+            timeout=60.0,
+        )
+        console.print("[green]✓ Platform project synced[/green]")
+    except FileNotFoundError:
+        # .cf/project.json is synthesized server-side now; we still PUT the
+        # local copy if present for UX parity, but it's not required.
+        pass
+    except SystemExit:
+        console.print("[yellow]⚠ HTTPS push succeeded but platform sync failed[/yellow]")
+    except Exception:
+        console.print("[yellow]⚠ Could not read project.json for platform sync[/yellow]")
+
+    if submit:
+        try:
+            _api_post(f"/projects/{platform_id}/submit", {})
+            console.print("[green]✓ Project submitted for review[/green]")
+        except SystemExit:
+            console.print("[yellow]⚠ Submit failed — ensure the project has a name[/yellow]")
+
+
 @main.command('push')
 @click.option('--project-root', required=False, type=click.Path(exists=True, file_okay=False), help='Path to the local ChipFoundry project directory (defaults to current directory if .cf/project.json exists).')
 @click.option('--sftp-host', default=DEFAULT_SFTP_HOST, show_default=True, help='SFTP server hostname.')
@@ -1569,8 +1842,25 @@ def _push_remote(project_root: Optional[str], project_name: Optional[str], dry_r
 @click.option('--dry-run', is_flag=True, help='Preview actions without uploading files.')
 @click.option('--submit', is_flag=True, help='Submit the project for review after upload.')
 @click.option('--remote', is_flag=True, help='Use the ChipFoundry GitHub App (HTTPS only) instead of SFTP. Useful when port 22 is blocked by a corporate firewall.')
-def push(project_root, sftp_host, sftp_username, sftp_key, project_id, project_name, project_type, force_overwrite, dry_run, submit, remote):
-    """Upload your project files to the ChipFoundry SFTP server (or via GitHub with --remote)."""
+@click.option('--https', 'https_mode', is_flag=True, help='Upload files directly over HTTPS (via S3 pre-signed URLs). Useful when both SFTP and GitHub are blocked.')
+def push(project_root, sftp_host, sftp_username, sftp_key, project_id, project_name, project_type, force_overwrite, dry_run, submit, remote, https_mode):
+    """Upload your project files to the ChipFoundry SFTP server.
+
+    Defaults to SFTP. Use --remote to push via the ChipFoundry GitHub App
+    (HTTPS), or --https to upload directly to AWS S3 (also HTTPS) without
+    needing Git. The two HTTPS modes are mutually exclusive.
+    """
+    if remote and https_mode:
+        console.print("[red]--remote and --https are mutually exclusive.[/red]")
+        raise click.Abort()
+    if https_mode:
+        _push_https(
+            project_root=project_root,
+            project_name=project_name,
+            dry_run=dry_run,
+            submit=submit,
+        )
+        return
     if remote:
         _push_remote(
             project_root=project_root,
@@ -1608,7 +1898,11 @@ def push(project_root, sftp_host, sftp_username, sftp_key, project_id, project_n
         sftp_username = me.get("sftp_username")
         if not sftp_username:
             console.print("[bold red]No SFTP account linked to your platform account.[/bold red]")
-            console.print("Contact support or provide --sftp-username.")
+            console.print(
+                "An SFTP account is provisioned once a project deposit is paid/waived/sponsored "
+                "and an SSH public key is on your profile."
+            )
+            console.print("Override with --sftp-username if you already know yours, or contact support.")
             raise click.Abort()
         config["sftp_username"] = sftp_username
         save_user_config(config)
@@ -1794,7 +2088,11 @@ def pull(project_name, output_dir, sftp_host, sftp_username, sftp_key):
         sftp_username = me.get("sftp_username")
         if not sftp_username:
             console.print("[bold red]No SFTP account linked to your platform account.[/bold red]")
-            console.print("Contact support or provide --sftp-username.")
+            console.print(
+                "An SFTP account is provisioned once a project deposit is paid/waived/sponsored "
+                "and an SSH public key is on your profile."
+            )
+            console.print("Override with --sftp-username if you already know yours, or contact support.")
             raise click.Abort()
         config["sftp_username"] = sftp_username
         save_user_config(config)
@@ -2078,24 +2376,34 @@ def status(sftp_host, sftp_username, sftp_key, json_output, show_all):
         platform_id = _load_project_platform_id(os.getcwd())
         if not platform_id:
             console.print("[dim]Tip: Run [bold]cf link[/bold] to connect this project to the platform.[/dim]\n")
+    # SFTP listing is a best-effort extra on top of the platform status above.
+    # Skip it quietly when the user has no SFTP account yet (auto-provisioned
+    # after a project deposit is paid/waived/sponsored + an SSH key is on file).
     if not sftp_username:
-        me = _api_get("/auth/cli/whoami")
-        sftp_username = me.get("sftp_username")
+        if config.get("api_key"):
+            try:
+                me = _api_get("/auth/cli/whoami")
+                sftp_username = me.get("sftp_username")
+            except SystemExit:
+                sftp_username = None
         if not sftp_username:
-            console.print("[red]No SFTP account linked to your platform account.[/red]")
-            console.print("Contact support or provide --sftp-username.")
-            raise click.Abort()
+            console.print(
+                "[dim]SFTP listing skipped — no SFTP account linked yet. "
+                "An account is provisioned once a project deposit is paid/waived/sponsored "
+                "and an SSH public key is on your profile.[/dim]"
+            )
+            return
         config["sftp_username"] = sftp_username
         save_user_config(config)
     if not sftp_key:
         sftp_key = config.get("sftp_key")
-    
+
     # Always resolve key_path to absolute path if set
     if sftp_key:
         key_path = os.path.abspath(os.path.expanduser(sftp_key))
     else:
         key_path = DEFAULT_SSH_KEY
-    
+
     if not os.path.exists(key_path):
         console.print(f"[red]SFTP key file not found: {key_path}[/red]")
         console.print("[yellow]Please run 'cf keygen' to generate a key or 'cf config' to set a custom key path.[/yellow]")
@@ -2221,7 +2529,11 @@ def tapeouts(sftp_host, sftp_username, sftp_key, limit, days):
         sftp_username = me.get("sftp_username")
         if not sftp_username:
             console.print("[red]No SFTP account linked to your platform account.[/red]")
-            console.print("Contact support or provide --sftp-username.")
+            console.print(
+                "An SFTP account is provisioned once a project deposit is paid/waived/sponsored "
+                "and an SSH public key is on your profile."
+            )
+            console.print("Override with --sftp-username if you already know yours, or contact support.")
             raise click.Abort()
         config["sftp_username"] = sftp_username
         save_user_config(config)
@@ -2411,7 +2723,11 @@ def confirm(project_root, sftp_host, sftp_username, sftp_key, project_name):
         sftp_username = me.get("sftp_username")
         if not sftp_username:
             console.print("[bold red]No SFTP account linked to your platform account.[/bold red]")
-            console.print("Contact support or provide --sftp-username.")
+            console.print(
+                "An SFTP account is provisioned once a project deposit is paid/waived/sponsored "
+                "and an SSH public key is on your profile."
+            )
+            console.print("Override with --sftp-username if you already know yours, or contact support.")
             raise click.Abort()
         config["sftp_username"] = sftp_username
         save_user_config(config)
@@ -3553,11 +3869,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 +3940,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 +4011,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 +4529,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,14 +4572,48 @@ 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
 
 
+def _format_api_error(resp) -> str:
+    """Build a user-friendly error message from a platform error response.
+
+    FastAPI returns errors as `{"detail": "..."}` (or a list of validation
+    errors). Surfacing that instead of the bare `Client error '409 Conflict'`
+    lets users act on the real reason without tailing backend logs.
+    """
+    status = resp.status_code
+    try:
+        body = resp.json()
+    except Exception:
+        snippet = (resp.text or "").strip()
+        if snippet:
+            return f"HTTP {status}: {snippet[:300]}"
+        return f"HTTP {status}"
+    detail = body.get("detail") if isinstance(body, dict) else None
+    if isinstance(detail, str) and detail:
+        return f"HTTP {status}: {detail}"
+    if isinstance(detail, list) and detail:
+        parts = []
+        for item in detail:
+            if isinstance(item, dict):
+                loc = ".".join(str(p) for p in (item.get("loc") or [])[-2:])
+                msg = item.get("msg") or ""
+                parts.append(f"{loc}: {msg}" if loc else msg)
+        if parts:
+            return f"HTTP {status}: {'; '.join(parts)}"
+    return f"HTTP {status}: {body}"
+
+
 def _api_get(path: str):
     """Authenticated GET to the platform API. Returns parsed JSON or raises SystemExit."""
+    import httpx as _httpx
     client, _ = _api_client()
     try:
         resp = client.get(path)
@@ -4217,6 +4624,9 @@ def _api_get(path: str):
         return resp.json()
     except SystemExit:
         raise
+    except _httpx.HTTPStatusError as e:
+        console.print(f"[red]✗ API request failed: {_format_api_error(e.response)}[/red]")
+        raise SystemExit(1)
     except Exception as e:
         console.print(f"[red]✗ API request failed: {e}[/red]")
         raise SystemExit(1)
@@ -4231,6 +4641,7 @@ def _api_post(path: str, json_data: dict, timeout: Optional[float] = None):
     Use a large value for long-running endpoints such as remote-push, which
     waits for the platform to fetch files from GitHub and stage them on EFS.
     """
+    import httpx as _httpx
     client, _ = _api_client()
     try:
         kwargs = {"json": json_data}
@@ -4244,6 +4655,9 @@ def _api_post(path: str, json_data: dict, timeout: Optional[float] = None):
         return resp.json()
     except SystemExit:
         raise
+    except _httpx.HTTPStatusError as e:
+        console.print(f"[red]✗ API request failed: {_format_api_error(e.response)}[/red]")
+        raise SystemExit(1)
     except Exception as e:
         console.print(f"[red]✗ API request failed: {e}[/red]")
         raise SystemExit(1)
@@ -4256,6 +4670,7 @@ def _api_put(path: str, json_data: dict, timeout: Optional[float] = None):
 
     `timeout` (seconds) overrides the client default for this request only.
     """
+    import httpx as _httpx
     client, _ = _api_client()
     try:
         kwargs = {"json": json_data}
@@ -4269,6 +4684,9 @@ def _api_put(path: str, json_data: dict, timeout: Optional[float] = None):
         return resp.json()
     except SystemExit:
         raise
+    except _httpx.HTTPStatusError as e:
+        console.print(f"[red]✗ API request failed: {_format_api_error(e.response)}[/red]")
+        raise SystemExit(1)
     except Exception as e:
         console.print(f"[red]✗ API request failed: {e}[/red]")
         raise SystemExit(1)
@@ -4435,7 +4853,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 +4879,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 +4954,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.4/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.4}/pyproject.toml

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