deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/_negative_args.py

@@ -0,0 +1,133 @@
+"""Click command class that accepts negative numbers in positional slots.
+
+Click reads any token starting with ``-`` as an option, so a negative literal
+written where a VALUE belongs dies before the command body runs::
+
+    $ deepcell edit model.deepcell ResearchSpend W17 -166667
+    Error: No such option: -1
+
+POSIX's ``--`` escape works, but nothing in ``--help`` mentions it, and
+financial models are full of negative literals — costs, ledger-signed spend,
+downward adjustments (issue #1290).
+
+The rescue is deliberately narrow. ``ignore_unknown_options`` would fix the
+parse by turning *every* unknown option into a positional, so a typo like
+``edit FILE ITEM CTX --scenarioo`` would be written into the document as the
+string ``"--scenarioo"``. Instead we let Click parse normally and only step in
+*after* it has already failed with ``NoSuchOption``, re-parsing with the
+offending token moved behind ``--``. The success path is untouched, and a
+mistyped option — which never looks like a number — still fails loudly with
+Click's own "Did you mean …?" suggestion.
+
+Only for commands whose negative-capable positional is **last**: escaped
+tokens are appended after the other arguments, which preserves positional
+order only if nothing positional follows them.
+"""
+
+from __future__ import annotations
+
+import re
+
+import click
+
+# Applied to ``NoSuchOption.option_name``, which Click truncates to the first
+# two characters for short-option-style tokens (``-166667`` is reported as
+# ``-1``, ``-.5`` as ``-.``). Anything else — ``--scenarioo``, ``-x`` — is a
+# real unknown option and must keep failing.
+_UNKNOWN_LOOKS_NUMERIC = re.compile(r"^-[\d.]")
+
+# Applied to the full token to decide what may be rescued: an optionally
+# thousands-separated decimal, with optional exponent or trailing percent.
+_NEGATIVE_NUMBER = re.compile(
+    r"""^-
+        (?:\d[\d,]*)?        # integer part, e.g. 1,234
+        (?:\.\d+)?           # fraction, e.g. .50
+        (?:[eE][-+]?\d+)?    # exponent, e.g. e6
+        %?$                  # percent literal, e.g. -12%
+    """,
+    re.VERBOSE,
+)
+
+
+def _is_negative_number(token: str) -> bool:
+    return bool(_NEGATIVE_NUMBER.match(token)) and any(c.isdigit() for c in token)
+
+
+class NegativeNumberCommand(click.Command):
+    """A ``click.Command`` that tolerates negative numbers as positionals."""
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        pending = list(args)
+        escaped: list[str] = []
+        # Bounded by the number of tokens: each retry escapes exactly one.
+        for _ in range(len(pending) + 1):
+            try:
+                return super().parse_args(ctx, self._compose(pending, escaped))
+            except click.NoSuchOption as exc:
+                index = self._rescuable_index(pending, exc)
+                if index is None:
+                    raise self._with_hint(ctx, exc) from None
+                escaped.append(pending.pop(index))
+        return super().parse_args(ctx, self._compose(pending, escaped))
+
+    @staticmethod
+    def _compose(pending: list[str], escaped: list[str]) -> list[str]:
+        return [*pending, "--", *escaped] if escaped else list(pending)
+
+    def _rescuable_index(
+        self, pending: list[str], exc: click.NoSuchOption
+    ) -> int | None:
+        """Index of the negative-number token that broke the parse, if any."""
+        if not _UNKNOWN_LOOKS_NUMERIC.match(exc.option_name or ""):
+            return None
+        # The caller already wrote a `--`; a second one would be parsed as a
+        # positional value, so leave their argv alone.
+        if "--" in pending:
+            return None
+
+        value_opts = self._value_taking_opts()
+        i = 0
+        while i < len(pending):
+            token = pending[i]
+            # Click consumes the token after a value option even when it starts
+            # with `-`, so `--scenario -1` is already fine and must not be
+            # mistaken for the broken positional.
+            if token in value_opts:
+                i += 2
+                continue
+            if _is_negative_number(token):
+                return i
+            i += 1
+        return None
+
+    def _value_taking_opts(self) -> set[str]:
+        opts: set[str] = set()
+        for param in self.params:
+            if not isinstance(param, click.Option):
+                continue
+            if param.is_flag or getattr(param, "count", False):
+                continue
+            opts.update(param.opts)
+            opts.update(param.secondary_opts)
+        return opts
+
+    def _with_hint(
+        self, ctx: click.Context, exc: click.NoSuchOption
+    ) -> click.NoSuchOption:
+        """Point at ``--`` for leading-dash values we could not rescue."""
+        name = exc.option_name or ""
+        if not name.startswith("-") or name.startswith("--"):
+            return exc
+        # Click reports the first short option it could not resolve, which for
+        # `-xyz` is just `-x` — so the hint names the slot, not the token.
+        metavar = "VALUE"
+        for param in self.params:
+            if isinstance(param, click.Argument):
+                metavar = param.name.upper()
+        exc.message = (
+            f"{exc.message}\n\n"
+            f"Hint: a literal {metavar} that starts with '-' must come after "
+            f"'--':\n"
+            f"  {ctx.command_path} ... -- {metavar}"
+        )
+        return exc

deepcell_cli/commands/_swapped_args.py

@@ -0,0 +1,153 @@
+"""Click command class that catches a swapped FILENAME / ID argument pair.
+
+Every `.deepcell`-addressing command puts the file first::
+
+    deepcell claim history model.deepcell c_thesis
+
+Write the two the other way round and the file lookup is what fails, so the
+error talks about the *id*::
+
+    $ deepcell claim history c_thesis model.deepcell
+    Error: File 'c_thesis' not found in workspace '722e186c-…'.
+           Available files: ['model.deepcell']
+
+Everything in that message is true and none of it names the mistake. The
+guide eval caught a reader doing exactly this (`calc-specificity` task-3,
+trace line 11) after they had just run several commands that take the id
+first in prose; recovering cost them a round trip they should not have paid.
+
+The rescue is deliberately narrow, for the same reason `_negative_args`'s is:
+it fires only when the FILENAME slot holds something that is *not* a document
+name **and** a later positional holds something that *is*. That pair is not a
+plausible spelling of any correct invocation — a real file named `c_thesis`
+would still not put `model.deepcell` in an id slot — so there is no shape this
+steals from the success path. Anything else (a genuinely missing file, a typo
+in the id) keeps failing exactly as it did.
+
+Sniffing the *extension* rather than asking the API keeps this free: the check
+runs before any network call, which is the point — the whole cost being saved
+is the round trip.
+"""
+
+from __future__ import annotations
+
+import click
+
+#: Suffixes that mark a token as a document name rather than a node id. Kept
+#: to what the workspace actually stores; `.xml` is deliberately absent, since
+#: these commands address workspace `.deepcell` files only.
+_DOCUMENT_SUFFIXES = (".deepcell",)
+
+#: The parameter holding the document name. Every command below declares it
+#: with this exact name, and the class asserts that rather than guessing, so a
+#: future command that names it differently fails loudly instead of silently
+#: opting out of the check.
+_FILE_PARAM = "filename"
+
+
+def _is_document(value: object) -> bool:
+    return isinstance(value, str) and value.endswith(_DOCUMENT_SUFFIXES)
+
+
+class FileFirstCommand(click.Command):
+    """Reject a FILENAME / ID pair that is obviously the wrong way round.
+
+    Applied to commands whose signature is ``FILENAME <ID>``. The check reads
+    only positional parameters: an option value that happens to end in
+    ``.deepcell`` (``--workspace`` never does, but ``--output`` could) is not
+    a positional and cannot be the swapped half of this pair.
+    """
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        rest = super().parse_args(ctx, args)
+        self._check_swapped(ctx)
+        return rest
+
+    def _check_swapped(self, ctx: click.Context) -> None:
+        params = {p.name: p for p in self.params}
+        file_param = params.get(_FILE_PARAM)
+        if file_param is None:  # pragma: no cover - guarded by the arg-order test
+            raise RuntimeError(
+                f"{self.name!r} uses FileFirstCommand but declares no "
+                f"{_FILE_PARAM!r} argument."
+            )
+
+        given_file = ctx.params.get(_FILE_PARAM)
+        if _is_document(given_file):
+            return
+
+        for name, param in params.items():
+            if name == _FILE_PARAM or not isinstance(param, click.Argument):
+                continue
+            value = ctx.params.get(name)
+            if isinstance(value, (tuple, list)):
+                # A variadic id slot: the
+                # document can be anywhere in it, so report the one that looks
+                # like a document rather than the whole tuple.
+                value = next((v for v in value if _is_document(v)), None)
+            if not _is_document(value):
+                continue
+            raise click.UsageError(
+                f"{value!r} looks like the document and {given_file!r} looks "
+                f"like the {name.upper()} — the arguments appear to be the "
+                f"wrong way round.\n"
+                f"The document always comes first:\n"
+                f"    {ctx.command_path} {value} {given_file}",
+                ctx=ctx,
+            )
+
+
+class FileFirstGroup(click.Group):
+    """Catch a document name handed to a GROUP that has no default action.
+
+    `claim` and `assumption` are groups: `deepcell claim history f.deepcell
+    c_thesis`. But `describe`, `query` and `cat` all take a document directly,
+    so `deepcell claim f.deepcell` is the natural analogy to draw — and Click
+    answers it by looking for a subcommand named `f.deepcell`::
+
+        $ deepcell claim model.deepcell
+        Error: No such command 'model.deepcell'.
+
+    True, and it names neither the mistake nor the fix. The reader has to
+    already know that `claim` is a group to decode it, which is exactly what
+    they did not know.
+
+    Same narrowness as `FileFirstCommand`: it fires only when the subcommand
+    slot holds something ending in `.deepcell`. No real subcommand is spelled
+    that way, so this steals nothing from the success path — a genuine typo in
+    a subcommand name still gets Click's own error, with its suggestions.
+    """
+
+    def resolve_command(self, ctx: click.Context, args: list[str]):
+        if args and _is_document(args[0]):
+            document = args[0]
+            raise click.UsageError(
+                f"{document!r} is a document, and {self.name!r} is a group of "
+                f"subcommands rather than a command that takes one.\n"
+                f"The subcommand comes first, then the document:\n"
+                + "\n".join(
+                    f"    {ctx.command_path} {self._usage(name, document)}"
+                    for name in sorted(self.commands)
+                ),
+                ctx=ctx,
+            )
+        return super().resolve_command(ctx, args)
+
+    def _usage(self, name: str, document: str) -> str:
+        """`history model.deepcell CLAIM_ID` — the subcommand's real signature.
+
+        One canned example with a `[ID]` bolted on would be wrong for whichever
+        subcommand does not take one, and the reader has no way to tell which.
+        Every subcommand in these groups is one line, so print them all with
+        the arguments they actually declare.
+        """
+        command = self.commands[name]
+        parts = [name]
+        for param in command.params:
+            if not isinstance(param, click.Argument):
+                continue
+            if param.name == _FILE_PARAM:
+                parts.append(document)
+            else:
+                parts.append((param.name or "arg").upper())
+        return " ".join(parts)

deepcell_cli/commands/_version_display.py

@@ -0,0 +1,40 @@
+"""Shared helper to display version history in CLI output."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+
+def echo_version_history(data: dict[str, Any]) -> None:
+    """Display version history summary if present in API response.
+
+    The footer is human-convenience metadata, so it is written to **stderr**
+    (like ``echo_success`` / ``echo_warning``) — keeping stdout machine-readable.
+    Otherwise it contaminates piped output: e.g. ``deepcell cat`` emits raw
+    ``.deepcell`` XML and the footer would land after ``</DeepCellDocument>``,
+    making the captured document invalid XML (issue #570).
+
+    Args:
+        data: API response dict that may contain a 'version_history' key.
+    """
+    vh = data.get("version_history")
+    if not vh:
+        return
+
+    commits = vh.get("commits", [])
+    total = vh.get("total", 0)
+    showing = vh.get("showing", 0)
+    head_sha = vh.get("head_sha", "")[:7] if vh.get("head_sha") else "none"
+
+    click.echo(f"\nVersion: {head_sha} ({showing} of {total} commits)", err=True)
+
+    if commits:
+        latest = commits[0]
+        # Truncate message to first line
+        title = latest["message"].split("\n", 1)[0]
+        click.echo(
+            f'Last change: "{title}" by {latest["author"]}, {latest["timestamp"]}',
+            err=True,
+        )

deepcell_cli/commands/_write_opts.py

@@ -0,0 +1,139 @@
+"""Click command classes that give every document-editing command ``-m``.
+
+Every command that edits a `.deepcell` writes a git commit, and the commit
+message is the only surviving record of *why*. The diff already shows what
+moved; nothing reconstructs the reason afterwards.
+
+That was true of the CLI long before it was uniform. `edit` took ``-m`` and
+``--title`` from the start; `doc` took ``-m`` but never ``--title``; the 47
+`defs` subcommands took neither until #1717's sibling fix injected ``-m``
+through ``_DefsCommand`` — and mapped it to the commit *subject* rather than
+the body, so the same flag meant two different things depending on which
+family you typed. The `reasoning` family took nothing at all, which is the
+sharpest version of the defect: the one surface whose entire subject matter is
+why the work says what it says was the one surface that could not record it
+(#1717). Its writes fell through to ``Update <filename>`` — the exact string
+the agent's own ``write_file`` override tells the model to avoid.
+
+So the rule this module enforces is a rule about *meaning*, not just about
+which flags parse:
+
+    ``-m`` (aliases ``--message`` / ``--rationale``) is always WHY, and lands
+    in ``rationale``. ``--title`` is always the commit SUBJECT, and lands in
+    ``title``. The mechanical summary the server would have written is never
+    lost — it survives as a ``Summary`` trailer.
+
+Injection rather than declaration, for the reason ``_DefsCommand`` records
+about ``--dry-run``: declared per-command the flag tracks who remembered to
+add it, not what the wire supports. The value is parked in ``ctx.meta`` so the
+~95 callback signatures stay unchanged.
+
+Applied per *command* for `doc` and `reasoning`, not per group: both groups
+mix reads and writes (`doc blocks`, `reasoning lint`), and a group-wide
+``command_class`` would hang a meaningless ``-m`` on a command that commits
+nothing. `defs` and `deck` stay group-wide — every command in them is a write.
+"""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.commands._negative_args import NegativeNumberCommand
+from deepcell_cli.commands._swapped_args import FileFirstCommand
+
+#: Where the parsed values are parked. ``ctx.meta`` rather than the callback
+#: signature so adding the options to a family does not touch its functions.
+_TITLE_META_KEY = "deepcell.write.title"
+_RATIONALE_META_KEY = "deepcell.write.rationale"
+
+#: Every spelling that means "why". The guard below checks ALL of them, not
+#: just the long name: ``_DefsCommand`` checked ``--message`` alone, so a
+#: future ``-m/--mode`` on some subcommand would have slipped past the skip
+#: and raised a duplicate-option error at import time — a failure that lands
+#: on whoever adds the unrelated flag, pointing at this file.
+_RATIONALE_SPELLINGS = ("-m", "--message", "--rationale")
+_TITLE_SPELLINGS = ("--title",)
+
+_RATIONALE_HELP = (
+    "Why this edit was made. Becomes the commit message body, so the history "
+    "reads as the decision rather than the coordinates the diff already "
+    "shows. `-m` and `--message` are aliases of `--rationale`."
+)
+_TITLE_HELP = (
+    "Short commit subject (e.g. 'Q3 actuals update'). Combined with "
+    "--rationale as 'title: rationale'. The mechanical summary the server "
+    "would have written is kept as a Summary trailer either way."
+)
+
+
+class WriteCommand(click.Command):
+    """A command that writes a commit — so it takes ``-m`` and ``--title``.
+
+    A subcommand that declares either option itself keeps its own: `edit`
+    spells both out and threads them through its own batch body, and `doc`
+    spells ``-m`` out because its callbacks take the value directly.
+    Declaring one is opting out of the injection for that flag only; the
+    other is still injected.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        declared = {
+            opt
+            for param in self.params
+            if isinstance(param, click.Option)
+            for opt in param.opts
+        }
+        #: What this class added, as opposed to what the command spelled out
+        #: itself. Only an injected option may be popped in ``invoke``: `doc`
+        #: declares an option literally named ``rationale`` and its callbacks
+        #: take that keyword, so popping it would be a TypeError on every doc
+        #: write. Recorded rather than re-derived, because the two are
+        #: indistinguishable from the parameter afterwards.
+        self.injected_write_opts: set[str] = set()
+        if not declared.intersection(_RATIONALE_SPELLINGS):
+            self.params.append(
+                click.Option(
+                    ["-m", "--message", "--rationale", "rationale"],
+                    default=None,
+                    help=_RATIONALE_HELP,
+                )
+            )
+            self.injected_write_opts.add("rationale")
+        if not declared.intersection(_TITLE_SPELLINGS):
+            self.params.append(
+                click.Option(["--title", "title"], default=None, help=_TITLE_HELP)
+            )
+            self.injected_write_opts.add("title")
+
+    def invoke(self, ctx: click.Context):
+        # ``pop`` rather than read: the callback never declared these, so
+        # leaving them in ``ctx.params`` is an unexpected-keyword TypeError.
+        # A command that declared its own keeps it — nothing to pop, and the
+        # callback receives it the ordinary way.
+        if "rationale" in self.injected_write_opts:
+            ctx.meta[_RATIONALE_META_KEY] = ctx.params.pop("rationale", None)
+        if "title" in self.injected_write_opts:
+            ctx.meta[_TITLE_META_KEY] = ctx.params.pop("title", None)
+        return super().invoke(ctx)
+
+
+class FileFirstWriteCommand(WriteCommand, FileFirstCommand):
+    """``FILENAME <ID>`` write commands — most of the `reasoning` family."""
+
+
+class NegativeNumberWriteCommand(WriteCommand, NegativeNumberCommand):
+    """A write command taking a negative literal in its last positional."""
+
+
+def write_message() -> tuple[str | None, str | None]:
+    """``(title, rationale)`` parked by :class:`WriteCommand` for this call.
+
+    Returns ``(None, None)`` outside a Click context, and for a command that
+    is not a :class:`WriteCommand` — the caller then supplies its own, which
+    is how `doc` passes the ``--rationale`` its callbacks declare.
+    """
+    ctx = click.get_current_context(silent=True)
+    if ctx is None:
+        return None, None
+    return ctx.meta.get(_TITLE_META_KEY), ctx.meta.get(_RATIONALE_META_KEY)

deepcell_cli/commands/account.py

@@ -0,0 +1,123 @@
+"""Account data-rights commands: export, delete.
+
+Thin pass-through to ``GET /auth/me/export`` and ``DELETE /auth/me``. These are
+the two rights the privacy policy says take effect immediately rather than by
+emailing support, so they exist as commands and not just as a mailbox.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from deepcell_cli.config import clear_credentials
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.errors import APIError
+from deepcell_cli.output import echo_error, echo_info, echo_success, output
+
+
+@click.group()
+def account() -> None:
+    """Export or delete the data held on your DeepCell account."""
+
+
+@account.command("export")
+@click.option(
+    "--output",
+    "-o",
+    "out_path",
+    type=click.Path(dir_okay=False, writable=True, path_type=Path),
+    default=None,
+    help="Write the export to this file instead of stdout.",
+)
+@pass_ctx
+def account_export(ctx: Ctx, out_path: Path | None) -> None:
+    """Download every record DeepCell holds about your account.
+
+    Includes your profile, workspaces, file index, share links, API key
+    metadata, sessions, and activity records. File *contents* are not included
+    — fetch those with `deepcell pull`. Authentication secrets are excluded by
+    design.
+    """
+    data = ctx.client.get("/auth/me/export")
+    if out_path is None:
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+    out_path.write_text(
+        json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    echo_success(f"Export written to {out_path}")
+
+
+@account.command("delete")
+@click.option(
+    "--confirm-email",
+    default=None,
+    help="Your account email. Prompted for if omitted.",
+)
+@click.option(
+    "--password",
+    default=None,
+    help="Account password. Prompted for if the account has one.",
+)
+@click.option(
+    "--yes",
+    is_flag=True,
+    help="Skip the interactive 'this is irreversible' confirmation.",
+)
+@pass_ctx
+def account_delete(
+    ctx: Ctx, confirm_email: str | None, password: str | None, yes: bool
+) -> None:
+    """Permanently delete your account and everything it owns.
+
+    This cannot be undone. Your workspaces, files, share links, and API keys
+    are destroyed, and your activity records are de-identified.
+
+    A workspace you share with other people is handed to another owner. If it
+    has no other owner, the deletion is refused so their data is not destroyed
+    with yours — transfer ownership or remove the other members first.
+    """
+    if confirm_email is None:
+        confirm_email = click.prompt("Confirm your account email")
+    if not yes:
+        click.confirm(
+            f"Permanently delete {confirm_email} and all of its data? "
+            "This cannot be undone.",
+            abort=True,
+        )
+    if password is None:
+        # An empty entry means "OAuth-only account, no password" — the server
+        # decides whether one was required, so we do not guess here.
+        password = (
+            click.prompt(
+                "Account password (leave blank if you sign in with Google)",
+                hide_input=True,
+                default="",
+                show_default=False,
+            )
+            or None
+        )
+
+    body: dict[str, str] = {"confirm_email": confirm_email}
+    if password:
+        body["password"] = password
+
+    try:
+        resp = ctx.client.delete("/auth/me", json=body)
+    except APIError as exc:
+        detail = exc.payload
+        if isinstance(detail, dict) and detail.get("workspaces"):
+            echo_error(detail.get("message", "Account deletion blocked."))
+            for workspace in detail["workspaces"]:
+                echo_info(f"  - {workspace.get('name')} ({workspace.get('id')})")
+            raise SystemExit(1) from exc
+        raise
+
+    output(resp.json(), ctx.fmt)
+    # The tokens on disk now authenticate nothing; leaving them would make the
+    # next command fail with a confusing 401 instead of "you are logged out".
+    clear_credentials()
+    echo_success("Account deleted. Local credentials have been cleared.")