deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/files.py

@@ -0,0 +1,386 @@
+"""File commands: ls, cat, write, rm."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from deepcell_cli.commands._version_display import echo_version_history
+from deepcell_cli.commands._write_opts import WriteCommand, write_message
+from deepcell_cli.commands.viewer import workbench_url
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import (
+    echo_success,
+    echo_validation,
+    echo_warning,
+    output,
+    output_mutation,
+    print_plain,
+)
+
+
+@click.command()
+@pass_ctx
+def ls(ctx: Ctx) -> None:
+    """List files in the active workspace."""
+    slug = ctx.require_workspace()
+    data = ctx.client.get(f"/workspaces/{slug}/files")
+    output(data, ctx.fmt)
+
+
+@click.command()
+@click.argument("filename")
+@click.option("--revision", default=None, help="Show file at specific revision.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def cat(ctx: Ctx, filename: str, revision: str | None, workspace_slug: str | None) -> None:
+    """Print file content (XML) to stdout.
+
+    To modify definition sections, use `deepcell replace` for targeted
+    string replacement. See `deepcell guide present/layout` for layout details.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    params: dict = {}
+    if revision:
+        params["revision"] = revision
+    data, read_revision = ctx.client.get_with_revision(
+        f"/workspaces/{slug}/files/{filename}", params=params or None
+    )
+    if isinstance(data, dict) and read_revision:
+        data.setdefault("revision", read_revision)
+    # The endpoint returns the file content — could be JSON with 'content' key or raw
+    if isinstance(data, dict) and "content" in data:
+        print_plain(data["content"])
+    else:
+        output(data, ctx.fmt)
+    # Surface the revision the bytes were read at (it travels as a response
+    # header, so it is otherwise invisible). It is the token that
+    # `deepcell write --revision` / `deepcell replace --revision` take, and
+    # therefore the only way a scripted read-modify-write can be safe against a
+    # concurrent editor. On **stderr**, like every other footer here: stdout
+    # carries the raw XML and must stay pipeable (#570).
+    if read_revision:
+        click.echo(f"Revision: {read_revision}", err=True)
+    if isinstance(data, dict):
+        echo_version_history(data)
+
+
+@click.command(cls=WriteCommand)
+@click.argument("filename")
+@click.option("--stdin", "from_stdin", is_flag=True, help="Read content from stdin.")
+@click.option("--file", "from_file", type=click.Path(exists=True), help="Read content from a local file.")
+@click.option("--content", "from_content", default=None, help="Pass file content inline (useful for MCP/programmatic access).")
+@click.option("--content-base64", "from_b64", default=None, help="Pass file content as a base64-encoded string.")
+@click.option(
+    "--revision",
+    default=None,
+    help="Expected revision SHA for optimistic locking — the `Revision:` line "
+    "`deepcell cat` prints on stderr. The write is refused with a conflict if "
+    "FILENAME changed since (a change to a different file is not a conflict).",
+)
+@click.option(
+    "--share/--no-share",
+    "want_share",
+    default=None,
+    help="Print a view-only share link for FILENAME as well. On by default "
+    "when you are not signed in, where it is the only URL that opens in a "
+    "browser; off by default when signed in, since the workbench link already "
+    "works. "
+    "An existing live link for the file is reused rather than duplicated.",
+)
+@pass_ctx
+def write(ctx: Ctx, filename: str, from_stdin: bool, from_file: str | None, from_content: str | None, from_b64: str | None, revision: str | None, want_share: bool | None) -> None:
+    """Create a file, or replace an existing one wholesale.
+
+    This writes the whole document: whatever is in the workspace under
+    FILENAME is replaced by the content you pass, not merged with it. To
+    change part of a document, edit it in place — `deepcell edit` for values,
+    `deepcell defs` for structure — which is almost always what you want.
+    The overwrite is a commit, so `deepcell log` and `deepcell restore` can
+    recover the previous content.
+
+    Provide content via --stdin (pipe), --file, --content, or --content-base64.
+
+    .deepcell files may include optional definition sections — run
+    `deepcell guide generate/values`, `deepcell guide revise/scenarios`,
+    or `deepcell ref format` for XML format details.
+
+    On success the command prints a browser URL for the file — the workbench
+    link when you are signed in, a public view link when you are not, so there
+    is always one to hand over. Relay it on the FIRST write and again when you
+    sign off, so the user follows the work rather than waiting for a report,
+    and still leaves with a link.
+
+    Both links are live: the page follows the file while you keep writing, so
+    the user watches the model take shape either way. The workbench offers each
+    change for review because its reader may be editing; a view-only share
+    simply updates. See `deepcell guide present/deliver`.
+    """
+    slug = ctx.require_workspace()
+
+    if from_content is not None:
+        content = from_content
+    elif from_b64:
+        import base64
+        try:
+            content = base64.b64decode(from_b64).decode("utf-8")
+        except Exception as exc:
+            raise click.UsageError(f"Invalid base64 content: {exc}")
+    elif from_stdin:
+        content = sys.stdin.read()
+    elif from_file:
+        with open(from_file) as fh:
+            content = fh.read()
+    else:
+        raise click.UsageError("Provide content with --stdin, --file, --content, or --content-base64.")
+
+    from deepcell_cli.errors import APIError
+    from deepcell_cli.revision import raise_if_stale, write_body
+
+    title, rationale = write_message()
+    body = write_body(
+        content, revision, title=title or None, rationale=rationale or None
+    )
+
+    try:
+        data = ctx.client.post(f"/workspaces/{slug}/files/{filename}", json=body)
+    except APIError as exc:
+        raise_if_stale(exc, filename=filename)
+        raise
+    # Resolve the browser link before emitting anything, so structured
+    # consumers (`-f json`, MCP) receive the URL as a field of the mutation
+    # payload rather than having to scrape it off stderr.
+    links = _browser_links(ctx, slug, filename, want_share=want_share)
+    if isinstance(data, dict):
+        for key, url in links.items():
+            data.setdefault(key, url)
+
+    errors = echo_validation(data)
+    output_mutation(data, ctx.fmt, plain_key="commit_sha")
+    if errors:
+        # The server persists invalid .deepcell content on purpose (computed
+        # values stay fresh; errors ride along in `validation`), so the save
+        # is real — but it must not read as a clean success or exit 0.
+        echo_warning(
+            f"File '{filename}' saved with {len(errors)} validation error(s) — "
+            "fix the errors above and write again"
+        )
+    else:
+        echo_success(f"File '{filename}' saved")
+    _echo_browser_links(filename, links)
+    if isinstance(data, dict):
+        echo_version_history(data)
+    if errors:
+        click.get_current_context().exit(1)
+
+
+def _browser_links(
+    ctx: Ctx, slug: str, filename: str, *, want_share: bool | None
+) -> dict[str, str]:
+    """Browser URLs to hand back for a just-written FILENAME.
+
+    A URL, not a command to run next: the reason to offer the link this early
+    is that the page follows the file while the agent is still working (#1553),
+    on both surfaces — the share page polls `/share/{token}/head`. A follow-up command they have to be told to run arrives
+    too late to be that — and a write that hands back nothing leaves an
+    anonymous session with no way into the browser at all.
+
+    So there is always a link, and which one follows from the session. Signed
+    in, it is the workbench URL: built locally, free, and the owner's own
+    editing surface. Anonymous, it is a view-only share link, because the
+    browser cannot sign in as the CLI's device-keyed identity — that costs a
+    request, and it is worth one.
+
+    ``want_share`` overrides the choice in both directions: ``True`` adds a
+    share link to a signed-in write (the hand-off case), ``False`` suppresses
+    minting entirely for a caller that does not want a capability token created
+    on its behalf.
+    """
+    from deepcell_cli.config import is_anonymous_session
+
+    links: dict[str, str] = {}
+    is_document = filename.endswith(".deepcell")
+    anonymous = is_anonymous_session()
+    if is_document and not anonymous:
+        links["browser_url"] = workbench_url(slug, filename)
+    share_wanted = (
+        want_share if want_share is not None else (is_document and anonymous)
+    )
+    if share_wanted:
+        share = _ensure_view_share(ctx, slug, filename)
+        if share:
+            links["share_url"] = share[0]
+            # The raw timestamp, not the date shown to a human: a machine
+            # reading this wants to compare it, and the day it lapses on
+            # depends on the reader's timezone.
+            if share[1]:
+                links["share_expires_at"] = share[1]
+    return links
+
+
+def _ensure_view_share(
+    ctx: Ctx, slug: str, filename: str
+) -> tuple[str, str | None] | None:
+    """This file's view link and its expiry — the one it has, or a new one."""
+    return _live_view_share(ctx, slug, filename) or _create_view_share(
+        ctx, slug, filename
+    )
+
+
+def _live_view_share(
+    ctx: Ctx, slug: str, filename: str
+) -> tuple[str, str | None] | None:
+    """A usable view link this file already has, if any.
+
+    A write is not a new thing to share. It is a new revision of the thing the
+    link already points at, and a link tracks the file rather than the revision
+    — so minting one per write would leave a document trailing a pile of live
+    capability tokens, each independently leakable and each needing its own
+    revoke. Look before creating.
+
+    A failure to look is not a failure to write: fall through to minting rather
+    than reporting an error for a link the caller did not ask about by name.
+    """
+    from deepcell_cli.config import frontend_base_url
+    from deepcell_cli.errors import APIError
+
+    try:
+        rows = ctx.client.get(
+            f"/workspaces/{slug}/shares", params={"filename": filename}
+        )
+    except APIError:
+        return None
+    if not isinstance(rows, list):
+        return None
+    for row in rows:
+        if not isinstance(row, dict) or row.get("permission") != "view":
+            continue
+        # A password-protected link is not one the holder can simply open, so
+        # it does not answer "give the user something to look at".
+        if row.get("has_password") or not row.get("share_token"):
+            continue
+        expires_at = row.get("expires_at")
+        if not _link_still_live(expires_at):
+            continue
+        url = f"{frontend_base_url()}/share/{row['share_token']}"
+        return url, str(expires_at) if expires_at else None
+    return None
+
+
+def _link_still_live(expires_at: object) -> bool:
+    """Whether a listed link has not lapsed.
+
+    The listing filters on ``is_active``, which revocation clears — expiry does
+    not, so an expired row still comes back. Handing out a dead URL is worse
+    than minting a fresh link, and an expiry that cannot be read is not evidence
+    the link works, so an unparseable value counts as lapsed.
+    """
+    if not expires_at:
+        return True
+    from datetime import datetime, timezone
+
+    try:
+        parsed = datetime.fromisoformat(str(expires_at).replace("Z", "+00:00"))
+    except ValueError:
+        return False
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed > datetime.now(timezone.utc)
+
+
+def _create_view_share(
+    ctx: Ctx, slug: str, filename: str
+) -> tuple[str, str | None] | None:
+    """Mint a view-only share link, or warn and return None.
+
+    The write already succeeded and is not undone by a failed share call, so a
+    sharing error is reported and stepped over rather than raised — losing the
+    "file saved" result to a link problem would be the worse outcome.
+    """
+    from deepcell_cli.config import frontend_base_url
+    from deepcell_cli.errors import APIError
+
+    try:
+        row = ctx.client.post(
+            f"/workspaces/{slug}/shares",
+            json={"filename": filename, "permission": "view"},
+        )
+    except APIError as exc:
+        echo_warning(
+            f"File saved, but the share link could not be created: {exc}. "
+            f"Retry with `deepcell share create {filename}`."
+        )
+        return None
+    token = row.get("share_token") if isinstance(row, dict) else None
+    if not token:
+        return None
+    expires_at = row.get("expires_at")
+    return (
+        f"{frontend_base_url()}/share/{token}",
+        str(expires_at) if expires_at else None,
+    )
+
+
+def _echo_browser_links(filename: str, links: dict[str, str]) -> None:
+    """Print the links on stderr, keeping stdout to the commit sha."""
+    if links.get("browser_url"):
+        click.echo(f"Open it in the browser: {links['browser_url']}", err=True)
+    if links.get("share_url"):
+        # Say when it dies, on the line that hands it over. Every link expires,
+        # and a URL presented with no lifetime reads like a permanent one — the
+        # holder finds out it lapsed by clicking a dead page.
+        expires = _expiry_date(links.get("share_expires_at"))
+        label = f"Share link (view, expires {expires})" if expires else "Share link (view)"
+        click.echo(f"{label}: {links['share_url']}", err=True)
+    if not links and filename.endswith(".deepcell"):
+        # Only reachable with `--no-share` on a session with no workbench URL:
+        # the caller refused the one link that session can offer.
+        click.echo(
+            f"No link printed (--no-share). `deepcell share create {filename}` "
+            "makes one.",
+            err=True,
+        )
+
+
+def _expiry_date(expires_at: object) -> str | None:
+    """The calendar day a link lapses on, for a human reading one line.
+
+    The full timestamp goes to structured consumers; a person handing a link to
+    a colleague needs the day, and a date is what they will repeat out loud.
+    An unreadable value prints nothing rather than a guess.
+    """
+    if not expires_at:
+        return None
+    from datetime import datetime
+
+    try:
+        parsed = datetime.fromisoformat(str(expires_at).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed.date().isoformat()
+
+
+@click.command()
+@click.argument("filename")
+@click.option("-y", "--yes", is_flag=True, help="Skip confirmation prompt.")
+@pass_ctx
+def rm(ctx: Ctx, filename: str, yes: bool) -> None:
+    """Delete a file from the workspace.
+
+    The deletion is a commit, so the file is recoverable: `deepcell log` finds
+    the revision before it and `deepcell restore <revision>` or `deepcell
+    download <file> --revision <revision>` brings it back.
+    """
+    if not yes:
+        click.confirm(f"Are you sure you want to delete '{filename}'?", abort=True)
+    slug = ctx.require_workspace()
+    resp = ctx.client.delete(f"/workspaces/{slug}/files/{filename}")
+    # Show the deletion commit so it can be referenced / restored past later.
+    # (delete returns the raw response; 204-no-body servers have no sha.)
+    try:
+        data = resp.json() if getattr(resp, "content", b"") else {}
+    except ValueError:
+        data = {}
+    output_mutation(data, ctx.fmt, plain_key="commit_sha")
+    echo_success(f"File '{filename}' deleted")

deepcell_cli/commands/grep.py

@@ -0,0 +1,90 @@
+"""``deepcell grep`` — client-side search within .deepcell files."""
+
+from __future__ import annotations
+
+import re
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_warning, output
+
+
+@click.command()
+@click.argument("pattern")
+@click.option("--file", "filename", default=None, help="Search within a specific file.")
+@click.option("-i", "--ignore-case", is_flag=True, help="Case-insensitive search.")
+@pass_ctx
+def grep(ctx: Ctx, pattern: str, filename: str | None, ignore_case: bool) -> None:
+    """Search for items/values matching a pattern in .deepcell files.
+
+    Matches against item ids, labels, and values. Each file is downloaded in
+    full to search it, so scope with --file when you know where to look.
+    """
+    slug = ctx.require_workspace()
+
+    # Determine files to search
+    if filename:
+        # An explicit --file must fail loudly on a bad name — pre-fix both a
+        # typo'd filename and a non-.deepcell file printed "(empty)" exit 0,
+        # indistinguishable from "no match".
+        if not filename.endswith(".deepcell"):
+            raise click.UsageError(
+                f"'{filename}' is not a .deepcell file — grep searches "
+                ".deepcell XML only."
+            )
+        filenames = [filename]
+    else:
+        files_data = ctx.client.get(f"/workspaces/{slug}/files")
+        if isinstance(files_data, list):
+            filenames = [
+                f.get("filename", f.get("name", ""))
+                for f in files_data
+                if isinstance(f, dict)
+            ]
+        else:
+            filenames = []
+
+    flags = re.IGNORECASE if ignore_case else 0
+    try:
+        regex = re.compile(pattern, flags)
+    except re.error as e:
+        raise click.ClickException(f"Invalid regex: {e}")
+
+    matches: list[dict] = []
+
+    for fname in filenames:
+        if not fname.endswith(".deepcell"):
+            continue
+
+        try:
+            file_data = ctx.client.get(f"/workspaces/{slug}/files/{fname}")
+            xml = file_data.get("content", "") if isinstance(file_data, dict) else ""
+        except Exception as exc:
+            if filename:
+                # Explicit --file: the fetch failure IS the answer.
+                raise click.ClickException(f"Could not read '{fname}': {exc}")
+            # Workspace sweep: keep searching the rest, but say what was skipped
+            # — a silent skip reads as "searched everything, no match".
+            echo_warning(f"skipped '{fname}' (could not read: {exc})")
+            continue
+
+        if not xml:
+            continue
+
+        for lineno, line in enumerate(xml.splitlines(), 1):
+            if regex.search(line):
+                matches.append(
+                    {
+                        "file": fname,
+                        "line": lineno,
+                        "content": line.strip(),
+                    }
+                )
+
+    if not matches and ctx.fmt == "plain":
+        # The generic empty-list placeholder "(empty)" scans as "empty file
+        # list"; say what actually happened.
+        click.echo("(no matches)")
+        return
+    output(matches, ctx.fmt)