deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/sync_state.py

@@ -0,0 +1,120 @@
+"""Sync metadata management for local <-> cloud workspace sync.
+
+Tracks which workspace a local directory is linked to, the last synced
+commit SHA, and per-file checksums so we can detect local vs remote changes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterable
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+SYNC_DIR = ".deepcell"
+SYNC_FILE = f"{SYNC_DIR}/sync.json"
+
+
+@dataclass
+class FileChecksum:
+    """Per-file sync state."""
+
+    git_sha: str  # server blob SHA at last sync
+    local_hash: str  # SHA-256 of content at last sync
+
+
+@dataclass
+class SyncState:
+    """Persisted sync metadata for a cloned workspace."""
+
+    workspace_slug: str
+    workspace_id: str
+    api_url: str
+    last_sync_sha: str = ""
+    file_checksums: dict[str, FileChecksum] = field(default_factory=dict)
+    active_variant: str = ""  # name of the checked-out variant, or "" for main
+
+
+def find_sync_root(start_path: Path | None = None) -> Path | None:
+    """Walk up from *start_path* (default CWD) looking for `.deepcell/sync.json`."""
+    p = (start_path or Path.cwd()).resolve()
+    while True:
+        if (p / SYNC_FILE).is_file():
+            return p
+        parent = p.parent
+        if parent == p:
+            return None
+        p = parent
+
+
+def load_sync_state(root: Path) -> SyncState:
+    """Read and parse sync.json from *root*."""
+    data = json.loads((root / SYNC_FILE).read_text(encoding="utf-8"))
+    checksums = {
+        name: FileChecksum(**ck)
+        for name, ck in data.get("file_checksums", {}).items()
+    }
+    return SyncState(
+        workspace_slug=data["workspace_slug"],
+        workspace_id=data["workspace_id"],
+        api_url=data["api_url"],
+        last_sync_sha=data.get("last_sync_sha", ""),
+        file_checksums=checksums,
+        active_variant=data.get("active_variant", ""),
+    )
+
+
+def save_sync_state(root: Path, state: SyncState) -> None:
+    """Write sync.json to *root*/.deepcell/."""
+    sync_dir = root / SYNC_DIR
+    sync_dir.mkdir(parents=True, exist_ok=True)
+    raw: dict[str, Any] = {
+        "workspace_slug": state.workspace_slug,
+        "workspace_id": state.workspace_id,
+        "api_url": state.api_url,
+        "last_sync_sha": state.last_sync_sha,
+        "active_variant": state.active_variant,
+        "file_checksums": {
+            name: asdict(ck) for name, ck in state.file_checksums.items()
+        },
+    }
+    (root / SYNC_FILE).write_text(
+        json.dumps(raw, indent=2) + "\n", encoding="utf-8"
+    )
+
+
+def compute_local_hash(content: str) -> str:
+    """SHA-256 hex digest of *content*."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def scan_local_files(
+    root: Path, tracked: Iterable[str] = ()
+) -> dict[str, str]:
+    """Return {filename: sha256} for all non-hidden files under *root*.
+
+    Excludes the `.deepcell/` metadata directory, any dotfiles/dotdirs, and
+    `<file>.local` conflict backups — those are CLI-managed artifacts written
+    by `pull`, and tracking them made `push` upload them as real workspace
+    files (visible in `ls`, the web file list, and every future clone).
+
+    *tracked* is the set of filenames the sync state already knows about
+    (i.e. that came from the server). A `.local` name in that set is a real
+    workspace file, not a backup, and must be scanned: excluding it made
+    `push` classify it as deleted-locally and delete it server-side. Conflict
+    backups are written after the scan and never enter the sync state, so
+    they are never in *tracked*.
+    """
+    tracked_names = set(tracked)
+    result: dict[str, str] = {}
+    for p in root.iterdir():
+        if p.name.startswith("."):
+            continue
+        if p.name.endswith(".local") and p.name not in tracked_names:
+            continue
+        if p.is_file():
+            content = p.read_text(encoding="utf-8")
+            result[p.name] = compute_local_hash(content)
+    return result

deepcell_cli/upgrade_check.py

@@ -0,0 +1,399 @@
+"""Is a newer ``deepcell-cli`` published? — the automatic check behind the notice.
+
+Reading the answer and *fetching* it are deliberately separated:
+
+- every invocation reads a **cached** answer from disk (no network, no
+  latency) and, when that answer names a newer version, prints one notice to
+  **stderr** after the command's own output;
+- when the cached answer is older than :data:`CHECK_INTERVAL_SECONDS`, a
+  daemon thread refreshes it for *next* time, and the invocation waits up to
+  :data:`REFRESH_JOIN_SECONDS` at close for that thread to land its write.
+
+So the first run after a release is silent and the run after it warns. That
+is the trade for never adding latency to a command and never failing one
+because an index was unreachable — every path here swallows its own
+exceptions, because a version notice that can break ``deepcell cat`` is worse
+than no version notice.
+
+That bounded wait is not a hedge, it is what makes the refresh real. A daemon
+thread dies with the process, and a short command exits long before an HTTP
+round-trip returns: measured against the live indexes, the fetch takes ~0.15s
+while ``deepcell upgrade status`` and ``deepcell help`` finish in
+milliseconds, so the cache was never written and *no* number of runs ever
+warned. Only commands slow enough to outlive the fetch by luck
+(``rules --all``, ``example list``) primed it. The wait costs nothing on those
+— their thread has already finished, so the join returns at once — and it is
+reached at most once per :data:`CHECK_INTERVAL_SECONDS`, because a fresh cache
+is not stale and starts no thread at all. An index that hangs past the budget
+is abandoned exactly as before: the cache goes unwritten, and the command is
+not held up for it.
+
+Nothing is ever installed. The notice prints the exact command to run, since
+knowing a newer version exists is not the same as knowing how to get it — and
+the command belongs to the index that carries the release, not to this module.
+:data:`DEFAULT_INDEXES` names one index today, production PyPI, and the
+highest-version-wins loop in :func:`fetch_latest` is what keeps that a data
+change rather than a code change (``DEEPCELL_UPGRADE_INDEX_URL`` overrides it).
+
+The notice goes to stderr, never stdout — ``deepcell cat`` emits raw
+``.deepcell`` XML, and a footer on stdout makes the captured document invalid
+(issue #570, the same reason ``echo_version_history`` writes to stderr).
+
+Off switches, in precedence order:
+
+- ``DEEPCELL_NO_UPGRADE_CHECK=1`` — this invocation (and everything a hosted
+  process spawns), without writing to a config file it may share;
+- ``deepcell upgrade disable`` — persistently, in ``config.json``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+import time
+from pathlib import Path
+from typing import Any, NamedTuple
+
+import click
+
+from deepcell_cli import __version__
+from deepcell_cli.config import load_config, save_config, save_state_file, state_file
+
+PACKAGE_NAME = "deepcell-cli"
+
+CONFIG_KEY = "auto_upgrade_check"
+ENV_DISABLE = "DEEPCELL_NO_UPGRADE_CHECK"
+ENV_INDEX = "DEEPCELL_UPGRADE_INDEX_URL"
+
+STATE_FILENAME = "upgrade-check.json"
+CHECK_INTERVAL_SECONDS = 24 * 60 * 60
+FETCH_TIMEOUT_SECONDS = 3.0
+
+#: How long an invocation will wait at close for a refresh it started to write
+#: its answer. Deliberately far below the worst case of ``FETCH_TIMEOUT_SECONDS``
+#: per index: the point is to cover the ordinary fetch (~0.15s against the live
+#: indexes), not to make a command hostage to a stalled one.
+REFRESH_JOIN_SECONDS = 1.0
+
+
+class Index(NamedTuple):
+    """A package index to ask, and the command that installs from it."""
+
+    json_url: str
+    install_command: str
+
+
+# One index: `deepcell-cli` ships to production PyPI, which carries its
+# dependencies too, so the install line needs no index flags at all.
+#
+# `fetch_latest` still asks *every* index and takes the **highest** version
+# rather than the first that answers, and that is deliberate with a tuple of
+# one. The tuple is the seam a second index is added at — a mirror, a private
+# index via `DEEPCELL_UPGRADE_INDEX_URL`, a pre-release channel — and
+# first-answer-wins would then quietly stop noticing releases whenever the
+# earlier index lagged the later one. Nothing would fail; the check would just
+# say nothing forever, which is the failure mode this whole module is built to
+# avoid. (It is also what the TestPyPI era needed, when production PyPI 404'd.)
+DEFAULT_INDEXES = (
+    Index(
+        f"https://pypi.org/pypi/{PACKAGE_NAME}/json",
+        f"pip install --upgrade {PACKAGE_NAME}",
+    ),
+)
+
+# Daemon threads started by `start_background_refresh`, and the reason
+# `join_background_refresh` can find them at close. They are still daemons, so
+# an overrunning fetch never holds the interpreter open — the join, not the
+# thread, is what bounds the wait. (`main._TRACKING_THREADS` keeps the same
+# list for the same reason, minus the join: dropping an analytics POST costs
+# nothing, whereas dropping this write costs the whole feature.) The test
+# conftest also drains this list between tests.
+_REFRESH_THREADS: list[threading.Thread] = []
+
+
+# ── Version comparison (a subset of PEP 440) ────────────────
+
+_VERSION_RE = re.compile(
+    r"^\s*v?(?P<release>\d+(?:\.\d+)*)"
+    r"(?:[-_.]?(?P<label>dev|alpha|beta|preview|pre|post|rev|rc|a|b|c|r)"
+    r"[-_.]?(?P<num>\d+)?)?"
+    r"(?:\+[0-9a-zA-Z.]+)?\s*$"
+)
+
+# dev < alpha < beta < rc < final < post. A bare release sorts at _FINAL_RANK,
+# so 1.2.3 beats 1.2.3rc1 and loses to 1.2.3.post1.
+_LABEL_RANK = {
+    "dev": 0,
+    "a": 1,
+    "alpha": 1,
+    "b": 2,
+    "beta": 2,
+    "c": 3,
+    "rc": 3,
+    "pre": 3,
+    "preview": 3,
+    "post": 5,
+    "rev": 5,
+    "r": 5,
+}
+_FINAL_RANK = 4
+
+
+def parse_version(text: Any) -> tuple[tuple[int, ...], int, int] | None:
+    """Sort key for *text*, or ``None`` when it is not a version we understand.
+
+    A deliberate subset of PEP 440 — enough for ``1.2.3``, ``1.2.3rc1``,
+    ``1.2.3.post1`` and ``1.2.3.dev4``, which covers every shape this package
+    has published. Returning ``None`` rather than guessing is the point: an
+    unrecognised string must make the check say *nothing*, not invent an
+    ordering that tells a current install it is out of date.
+
+    Trailing zero segments are dropped so ``0.3`` and ``0.3.0`` compare equal.
+    """
+    if not isinstance(text, str):
+        return None
+    match = _VERSION_RE.match(text.lower())
+    if not match:
+        return None
+    release = tuple(int(part) for part in match.group("release").split("."))
+    while len(release) > 1 and release[-1] == 0:
+        release = release[:-1]
+    label = match.group("label") or ""
+    rank = _LABEL_RANK.get(label, _FINAL_RANK) if label else _FINAL_RANK
+    return release, rank, int(match.group("num") or 0)
+
+
+def is_newer(candidate: Any, current: str = __version__) -> bool:
+    """True when *candidate* is a version strictly ahead of *current*."""
+    left, right = parse_version(candidate), parse_version(current)
+    if left is None or right is None:
+        return False
+    return left > right
+
+
+# ── The setting ─────────────────────────────────────────────
+
+
+def config_enabled() -> bool:
+    """The persisted setting. Absent means on — the check is opt-out."""
+    return bool(load_config().get(CONFIG_KEY, True))
+
+
+def env_silenced() -> bool:
+    """True when this process was told to stay quiet regardless of config."""
+    return bool(os.environ.get(ENV_DISABLE, "").strip())
+
+
+def is_enabled() -> bool:
+    """True when the automatic check may run in this process.
+
+    The env var wins over the config file so a CI job, an MCP host, or any
+    other shared process can silence the notice without writing to a config
+    file that belongs to someone else.
+    """
+    return not env_silenced() and config_enabled()
+
+
+def set_enabled(enabled: bool) -> None:
+    """Persist the setting to ``config.json``."""
+    cfg = load_config()
+    cfg[CONFIG_KEY] = bool(enabled)
+    save_config(cfg)
+
+
+# ── Cached answer ───────────────────────────────────────────
+
+
+def state_path() -> Path:
+    return state_file(STATE_FILENAME)
+
+
+def read_state() -> dict[str, Any]:
+    """The cached answer, or ``{}`` when there is none / it is unreadable."""
+    try:
+        data = json.loads(state_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def is_stale(state: dict[str, Any] | None = None, now: float | None = None) -> bool:
+    """True when the cached answer is due for a refresh."""
+    state = read_state() if state is None else state
+    checked = state.get("checked_at")
+    if not isinstance(checked, (int, float)) or isinstance(checked, bool):
+        return True
+    age = (time.time() if now is None else now) - checked
+    # A negative age means the clock moved backwards, or the state file came
+    # from another machine. Refresh rather than trust it — the alternative is
+    # a cache that is never due again.
+    return not (0 <= age < CHECK_INTERVAL_SECONDS)
+
+
+# ── Fetching ────────────────────────────────────────────────
+
+
+def indexes() -> tuple[Index, ...]:
+    """The indexes to ask — ``DEEPCELL_UPGRADE_INDEX_URL`` overrides, comma-separated."""
+    raw = os.environ.get(ENV_INDEX, "").strip()
+    if not raw:
+        return DEFAULT_INDEXES
+    chosen: list[Index] = []
+    for url in (part.strip() for part in raw.split(",")):
+        if not url:
+            continue
+        known = next((i for i in DEFAULT_INDEXES if i.json_url == url), None)
+        chosen.append(known or Index(url, f"pip install --upgrade {PACKAGE_NAME}"))
+    return tuple(chosen) or DEFAULT_INDEXES
+
+
+def fetch_latest(timeout: float = FETCH_TIMEOUT_SECONDS) -> tuple[str, str] | None:
+    """Ask every configured index and return the highest release found.
+
+    Returns ``(version, install_command)``, or ``None`` when no index answered
+    with a version we can parse. An index that errors, times out, or 404s is
+    skipped, not fatal — one dead index must not hide a live one.
+    """
+    import httpx
+
+    best: tuple[tuple[tuple[int, ...], int, int], str, str] | None = None
+    for index in indexes():
+        try:
+            response = httpx.get(
+                index.json_url,
+                timeout=timeout,
+                follow_redirects=True,
+                headers={"Accept": "application/json"},
+            )
+            if response.status_code != 200:
+                continue
+            payload = response.json()
+            version = payload.get("info", {}).get("version")
+        except Exception:
+            continue
+        key = parse_version(version)
+        if key is None:
+            continue
+        if best is None or key > best[0]:
+            best = (key, version, index.install_command)
+    return None if best is None else (best[1], best[2])
+
+
+def refresh(timeout: float = FETCH_TIMEOUT_SECONDS) -> dict[str, Any]:
+    """Fetch, cache, and return the new state.
+
+    ``checked_at`` advances even when the fetch failed, so an offline machine
+    retries once a day instead of on every command. A previously-known
+    ``latest`` is kept on failure — a dropped network is no reason to forget
+    an upgrade that really is available.
+    """
+    result = fetch_latest(timeout)
+    state = read_state()
+    state["checked_at"] = time.time()
+    state["ok"] = result is not None
+    if result is not None:
+        state["latest"], state["install_command"] = result
+    try:
+        save_state_file(STATE_FILENAME, state)
+    except OSError:
+        pass
+    return state
+
+
+def start_background_refresh() -> None:
+    """Refresh the cache in a daemon thread. Never blocks, never raises."""
+
+    def _run() -> None:
+        try:
+            refresh()
+        except Exception:
+            pass
+
+    thread = threading.Thread(target=_run, daemon=True, name="deepcell-upgrade-check")
+    _REFRESH_THREADS.append(thread)
+    thread.start()
+
+
+def join_background_refresh(timeout: float = REFRESH_JOIN_SECONDS) -> None:
+    """Wait, briefly and at most once, for started refreshes to finish.
+
+    Without this the refresh is a write that never happens. ``_run`` is a
+    daemon, so the interpreter does not wait for it: a command that finishes
+    before the HTTP round-trip returns takes the thread down with it, mid
+    request, and ``save_state_file`` is never reached. Nothing fails and
+    nothing is logged — the cache simply stays empty, so the next run has no
+    answer to warn from either, and the notice never appears no matter how
+    many times the CLI is run.
+
+    *timeout* is a budget for the whole set, not per thread, so the delay a
+    command can inherit stays bounded however many refreshes were started.
+    Overrunning it is the pre-existing outcome, not a new failure: the write
+    is lost and the next invocation tries again.
+
+    Never raises — this runs from a Click close callback, outside
+    :func:`schedule`'s guard, and no upgrade check is worth failing a command.
+    """
+    try:
+        deadline = time.monotonic() + timeout
+        for thread in _REFRESH_THREADS:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return
+            thread.join(remaining)
+    except Exception:
+        return
+
+
+# ── The notice ──────────────────────────────────────────────
+
+
+def pending_notice(current: str = __version__) -> str | None:
+    """The stderr notice for the cached answer, or ``None`` when up to date."""
+    state = read_state()
+    latest = state.get("latest")
+    if not is_newer(latest, current):
+        return None
+    install = state.get("install_command") or f"pip install --upgrade {PACKAGE_NAME}"
+    return (
+        f"A newer deepcell is available: {current} -> {latest}\n"
+        f"  {install}\n"
+        f"  (silence this: deepcell upgrade disable)"
+    )
+
+
+def schedule(ctx: click.Context) -> None:
+    """Arrange this invocation's notice and, if due, its background refresh.
+
+    Called from the root group callback, so it runs once per invocation before
+    any subcommand. The notice is deferred to context close so it lands *after*
+    the command's own output rather than in front of it.
+
+    Swallows everything: no upgrade check is worth failing a command over.
+    """
+    try:
+        if not is_enabled():
+            return
+        notice = pending_notice()
+        if notice:
+            # Re-read the setting at emit time, not just here: this callback is
+            # registered *before* the subcommand runs, so `deepcell upgrade
+            # disable` would otherwise print one last notice on its way out and
+            # read as "disable didn't work".
+            def _emit() -> None:
+                if is_enabled():
+                    click.echo(notice, err=True)
+
+            ctx.call_on_close(_emit)
+        if is_stale():
+            start_background_refresh()
+            # Registered second, so Click's LIFO close order runs it before the
+            # notice above: the refresh gets the length of the command *plus*
+            # this budget to land, and the notice still reports the answer that
+            # was cached when the command started, which is the documented
+            # cadence — silent on the run that discovers a release, warning on
+            # the next one.
+            ctx.call_on_close(join_background_refresh)
+    except Exception:
+        return

deepcell_cli/xml_replace.py

@@ -0,0 +1,89 @@
+"""Pure string helpers for whitespace-tolerant XML replacement."""
+
+from __future__ import annotations
+
+
+def find_whitespace_tolerant_match(
+    file_content: str,
+    old_string: str,
+) -> str | None:
+    """Find old_string in file_content using whitespace-tolerant matching.
+
+    Strips leading/trailing whitespace from each line and ignores blank lines
+    when comparing.  Returns the actual text from the file (with original
+    indentation) if exactly one contiguous match is found, otherwise None.
+    """
+    file_content = file_content.replace("\r\n", "\n")
+    old_string = old_string.replace("\r\n", "\n")
+
+    file_lines = file_content.split("\n")
+    old_lines = old_string.split("\n")
+
+    # Build normalized (non-empty, stripped) lines with index mapping
+    norm_file: list[tuple[int, str]] = []
+    for i, line in enumerate(file_lines):
+        stripped = line.strip()
+        if stripped:
+            norm_file.append((i, stripped))
+
+    norm_old = [line.strip() for line in old_lines if line.strip()]
+
+    if not norm_old:
+        return None
+
+    # Slide normalized old_string across normalized file lines
+    matches: list[int] = []
+    for start in range(len(norm_file) - len(norm_old) + 1):
+        if all(
+            norm_file[start + j][1] == norm_old[j]
+            for j in range(len(norm_old))
+        ):
+            matches.append(start)
+
+    if len(matches) != 1:
+        return None
+
+    # Map back to original file line range
+    match_start = matches[0]
+    first_orig_line = norm_file[match_start][0]
+    last_orig_line = norm_file[match_start + len(norm_old) - 1][0]
+
+    return "\n".join(file_lines[first_orig_line : last_orig_line + 1])
+
+
+def normalize_new_string_indentation(
+    actual_old: str,
+    original_old: str,
+    new_string: str,
+) -> str:
+    """Adjust new_string indentation to match the file's actual indentation.
+
+    Computes the indentation delta between actual_old (from file) and
+    original_old (from the caller) using the first non-empty line pair,
+    then applies that delta to every line of new_string.
+    """
+    actual_lines = actual_old.split("\n")
+    original_lines = original_old.split("\n")
+
+    # Find indentation delta from first non-empty line pair
+    delta = 0
+    for a_line, o_line in zip(actual_lines, original_lines):
+        if a_line.strip() and o_line.strip():
+            a_indent = len(a_line) - len(a_line.lstrip())
+            o_indent = len(o_line) - len(o_line.lstrip())
+            delta = a_indent - o_indent
+            break
+
+    if delta == 0:
+        return new_string
+
+    result_lines: list[str] = []
+    for line in new_string.split("\n"):
+        if not line.strip():
+            result_lines.append(line)
+            continue
+        current_indent = len(line) - len(line.lstrip())
+        new_indent = max(0, current_indent + delta)
+        result_lines.append(" " * new_indent + line.lstrip())
+
+    return "\n".join(result_lines)