deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/ref.py

@@ -0,0 +1,279 @@
+"""``deepcell ref`` — generated enumerations, and the cross-reference resolver.
+
+Where ``guide`` explains a procedure and ``rules`` states an invariant, ``ref``
+answers "what values are legal here". Its content is derived from the
+implementation — the functions from the formula constants, the op kinds from
+the pydantic union the server validates against — so unlike a prose list it
+cannot disagree with the code.
+
+The second job is resolution: ``deepcell ref rule:R2`` and
+``deepcell ref guide:generate/calcs`` both work, so an agent holding a typed id
+from a lint finding or a topic's ``see_also`` has exactly one command to reach
+for and never has to work out which surface owns the name.
+
+See ``docs/cli-agent-surface.md`` §6.
+"""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import output, print_plain
+
+
+def _resolve_cmd_id(raw_id: str) -> dict:
+    """Resolve ``cmd:<invocation>`` against the live Click tree.
+
+    Raises rather than returning a stub for an unknown name: a resolver that
+    answers for every string is worse than none, because it would confirm a
+    citation to a command that does not exist — which is the failure the typed
+    id scheme is meant to make impossible.
+    """
+    from deepcell_cli.surface import build_commands
+
+    name = raw_id.partition(":")[2].strip()
+    commands = build_commands()
+    entry = commands.get(name)
+    if entry is None:
+        raise click.ClickException(
+            f"Cannot resolve id: {raw_id}\n"
+            f"No command named {name!r}. List them with: deepcell help"
+        )
+    return {
+        "id": f"cmd:{name}",
+        "kind": "cmd",
+        "name": name,
+        "summary": entry.get("summary", ""),
+        "command": f"deepcell {name} --help",
+        "example": entry.get("example"),
+        "see_also": entry.get("see_also") or [],
+    }
+
+
+def _render_entry(entry: dict) -> str:
+    """Format one resolved entry for human reading."""
+    lines: list[str] = []
+    header = entry.get("id") or entry.get("name") or ""
+    if header:
+        lines += [header, "=" * len(header), ""]
+
+    if entry.get("summary"):
+        lines += [str(entry["summary"]), ""]
+
+    for label, key in (
+        ("Signature", "signature"),
+        ("Arity", "arity"),
+        ("Category", "category"),
+        ("Severity", "severity"),
+        ("Command", "command"),
+        ("Endpoint", "endpoint"),
+        ("Family", "family"),
+        ("Model", "model"),
+        # A deck style pack's metadata (`ref:deck-style/<pack>`): the five
+        # fields to choose a pack by, printed before the prose so a reader
+        # comparing packs sees the same shape on each.
+        ("Audience", "audience"),
+        ("Formality", "formality"),
+        ("Density", "density"),
+        ("Reading", "reading_mode"),
+        ("Export", "export_fidelity"),
+    ):
+        value = entry.get(key)
+        if value:
+            lines.append(f"{label + ':':<12}{value}")
+    roles = entry.get("roles")
+    if isinstance(roles, dict) and roles:
+        lines.append(
+            f"{'Roles:':<12}" + " ".join(f"{name}={value}" for name, value in roles.items())
+        )
+
+    if entry.get("aliases"):
+        lines.append(f"{'Aliases:':<12}{', '.join(entry['aliases'])}")
+    if entry.get("house_rule"):
+        lines.append(
+            f"{'House rule:':<12}rule:{entry['house_rule']} — {entry.get('house_rule_title', '')}"
+        )
+    if entry.get("resolved_from"):
+        lines.append(f"{'Resolved:':<12}{entry['resolved_from']} → {entry['name']}")
+
+    for label, key in (("Required", "required"), ("Optional", "optional")):
+        fields = entry.get(key)
+        if fields:
+            lines.append("")
+            lines.append(f"{label}:")
+            lines += [f"  {f['name']}: {f['type']}" for f in fields]
+
+    if entry.get("fix"):
+        lines += ["", "Fix:", f"  {entry['fix']}"]
+    if entry.get("detail"):
+        lines += ["", str(entry["detail"])]
+
+    # A deck style pack's starters (`ref:deck-style/<pack>`) are drop-in
+    # strings; fenced so a terminal reader gets exactly what the `-f json`
+    # field carries and can pass it through unchanged.
+    for label, key, lang in (
+        ("Deck CSS — pass through set_presentation_deck_style verbatim", "css", "css"),
+        ("Slide HTML starter", "slide_html", "html"),
+        # A deck layout (`ref:deck-layout/<name>`): the class-only slide body
+        # `deck add-slide --layout` inserts, fenced for the same reason.
+        ("Layout HTML — class-only, on the shared vocabulary", "html", "html"),
+    ):
+        value = entry.get(key)
+        if value:
+            lines += ["", f"{label}:", f"```{lang}", str(value).rstrip("\n"), "```"]
+
+    for sense in entry.get("senses") or []:
+        lines += [
+            "",
+            f"  [{sense['id']}] {sense['meaning']}",
+            f"      commands: {', '.join(sense['commands'])}",
+        ]
+
+    if entry.get("over_mcp"):
+        lines += ["", str(entry["over_mcp"])]
+    if entry.get("body"):
+        lines += ["", str(entry["body"]).rstrip()]
+
+    return "\n".join(lines).rstrip()
+
+
+@click.command()
+@click.argument("target", nargs=-1)
+@click.option("--limit", default=40, show_default=True, help="Maximum search results.")
+@pass_ctx
+def ref(ctx: Ctx, target: tuple[str, ...], limit: int) -> None:
+    """Look up legal values, and resolve any typed id.
+
+    \b
+    List the namespaces:  deepcell ref
+    List one namespace:   deepcell ref function
+    Read one entry:       deepcell ref function/NPV
+    Resolve a typed id:   deepcell ref rule:R2
+    Search everything:    deepcell ref search sensitivity
+
+    Search is a leading word rather than a subcommand: a Click group with an
+    optional positional cannot tell `ref search` (the verb) from `ref search`
+    (a namespace called "search"), and the ambiguity surfaces as a confusing
+    "No such command" on the *second* word.
+    """
+    if target and target[0] == "search":
+        _search(ctx, " ".join(target[1:]).strip(), limit)
+        return
+
+    if not target:
+        _list_namespaces(ctx)
+        return
+
+    what = target[0]
+
+    # A typed id (`rule:R2`, `ref:function/NPV`) resolves across every surface;
+    # a bare `function` or `function/NPV` addresses this surface directly.
+    #
+    # A colon alone does not make an id: `ref:selector/range` documents
+    # `Item[CURRENT-11:CURRENT]`, so a reader pasting what they typed asks for
+    # `selector/CURRENT-11:CURRENT`, which resolved to the nonexistent prefix
+    # `selector/CURRENT-11` and answered "cannot resolve" to a *legal*
+    # selector. A typed id's prefix is a fixed word and so never contains a
+    # `/`; a `/` before the first `:` means this is a namespace path whose name
+    # holds a colon. The authority is `src.core.ref.ids.looks_like_typed_id` —
+    # duplicated here because this package cannot import the backend, the same
+    # way the two `guide` index renderers agree by rule rather than by import.
+    if ":" in what and "/" not in what.partition(":")[0]:
+        raw_id = " ".join(target).strip()
+        if raw_id.startswith("cmd:"):
+            # Answered here, not by /ref/resolve. The command catalog is built
+            # from the live Click tree, which exists only in this package —
+            # backend/'s Docker build context excludes docs/cli-surface.json,
+            # so a server-side resolver would need a shipped copy of the tree
+            # and could drift from the commands that actually exist. This one
+            # cannot be wrong about that.
+            _print_entry(ctx, _resolve_cmd_id(raw_id))
+            return
+        _print_entry(ctx, ctx.client.get("/ref/resolve", params={"id": raw_id}))
+        return
+
+    namespace, _, name = what.partition("/")
+    if name:
+        _print_entry(ctx, ctx.client.get(f"/ref/{namespace}/{name}"))
+        return
+
+    _list_entries(ctx, namespace)
+
+
+def _print_entry(ctx: Ctx, data: object) -> None:
+    if ctx.fmt == "json":
+        output(data, ctx.fmt)
+        return
+    print_plain(_render_entry(data) if isinstance(data, dict) else str(data))
+
+
+def _list_namespaces(ctx: Ctx) -> None:
+    data = ctx.client.get("/ref")
+    namespaces = data.get("namespaces", []) if isinstance(data, dict) else data
+    if ctx.fmt == "json" or not isinstance(namespaces, list) or not namespaces:
+        output(data, ctx.fmt)
+        return
+    width = max(len(str(n.get("name", ""))) for n in namespaces)
+    lines = [
+        f"{str(n.get('name','')):<{width}}  {str(n.get('count','')):>4}  "
+        f"{n.get('description','')}"
+        for n in namespaces
+    ]
+    lines += [
+        "",
+        "List one:   deepcell ref <namespace>",
+        "Read one:   deepcell ref <namespace>/<name>",
+        "Resolve:    deepcell ref <typed-id>       e.g. rule:R2",
+        "Search:     deepcell ref search <text>",
+    ]
+    print_plain("\n".join(lines))
+
+
+def _list_entries(ctx: Ctx, namespace: str) -> None:
+    data = ctx.client.get(f"/ref/{namespace}")
+    entries = data.get("entries", []) if isinstance(data, dict) else data
+    if ctx.fmt == "json" or not isinstance(entries, list) or not entries:
+        output(data, ctx.fmt)
+        return
+    width = max(len(str(e.get("name", ""))) for e in entries)
+    lines = [
+        f"{str(e.get('name','')):<{width}}  {e.get('summary','')}" for e in entries
+    ]
+    lines += ["", f"Read one: deepcell ref {namespace}/<name>"]
+    print_plain("\n".join(lines))
+
+
+def _search(ctx: Ctx, text: str, limit: int) -> None:
+    """Search every surface at once and return typed ids.
+
+    Results say what *kind* of thing was found, so a search for "sensitivity"
+    that turns up an op kind, a guide topic and a rule can be told apart
+    without a second call to work out which command reads which.
+    """
+    if not text:
+        print_plain("Usage: deepcell ref search <text>")
+        return
+
+    data = ctx.client.get("/ref/search", params={"q": text, "limit": limit})
+    results = data.get("results", []) if isinstance(data, dict) else data
+
+    if ctx.fmt == "json":
+        output(data, ctx.fmt)
+        return
+    if not isinstance(results, list) or not results:
+        print_plain(f"No matches for '{text}'.")
+        return
+
+    width = max(len(str(r.get("id", ""))) for r in results)
+    lines: list[str] = []
+    for r in results:
+        lines.append(f"{str(r.get('id','')):<{width}}  {r.get('summary','')}")
+        # A snippet means the summary above did NOT contain the search term —
+        # the match is deeper in the entry. Printing it is what stops such a
+        # row reading as a mismatch: without it the reader sees a summary with
+        # none of their words in it and concludes the search is broken.
+        if r.get("snippet"):
+            lines.append(f"{'':<{width}}  ↳ {r['snippet']}")
+    lines += ["", "Read one: deepcell ref <id>"]
+    print_plain("\n".join(lines))

deepcell_cli/commands/replace.py

@@ -0,0 +1,326 @@
+"""Raw-XML string replacement in a workspace file.
+
+Split out of ``edit`` because the two do not share an exit-1 sense. ``edit``
+applies a batch of value changes and reports which rows landed, so a failure is
+**partially applied**. ``replace`` writes the file *first* and validates the
+result *after*, so a failure means the replacement is already on disk and the
+document is invalid — ``written-but-invalid``. ``cli/src/deepcell_cli/
+surface.py`` maps exit senses over command paths, so one command carrying two
+senses was inexpressible; two commands is.
+
+``edit --replace`` stays as a deprecated alias (it calls :func:`do_replace`
+directly) so existing scripts and agent transcripts keep working.
+"""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+from deepcell_cli.commands._batch_input import read_batch_payload
+from deepcell_cli.commands._write_opts import WriteCommand, write_message
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import (
+    echo_success,
+    echo_validation,
+    echo_warning,
+    output_mutation,
+)
+
+
+@click.command("replace", cls=WriteCommand)
+@click.argument("filename")
+@click.argument("old_string", required=False)
+@click.argument("new_string", required=False)
+@click.option("--replace-all", is_flag=True, help="Replace every occurrence instead of requiring a unique match.")
+@click.option(
+    "--batch",
+    "batch_file",
+    help='Replacement as a JSON object {"old_string": "...", "new_string": "..."} '
+    "— a file path, '-' for stdin, or inline JSON. Use this for multiline XML.",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def replace(
+    ctx: Ctx,
+    filename: str,
+    old_string: str | None,
+    new_string: str | None,
+    replace_all: bool,
+    batch_file: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Replace raw XML text in a file — the last-resort editor.
+
+    \b
+    Prefer a typed command where one exists:
+      Values                     `deepcell edit FILE ITEM CONTEXT VALUE`
+      Structure / formulas       `deepcell defs add-calc / add-item / ...`
+      Raw XML (this command)     sections with no typed op (Sources, ...)
+
+    \b
+    Exit 1 here does NOT mean nothing happened. The file is written first and
+    validated second, so exit 1 means the replacement IS already in the file
+    and the document is now invalid — read the errors and fix forward.
+
+    \b
+    Matching is tiered, server-side: exact → whitespace-tolerant →
+    canonicalization-aware (the server rewrites XML on every write, so an
+    old_string composed from what you previously *wrote* may no longer be the
+    stored spelling). A non-exact match is reported, because the bytes it
+    rewrote are not the bytes you passed.
+
+    \b
+    Examples:
+      deepcell replace model.deepcell "<Old>text</Old>" "<New>text</New>"
+      deepcell replace model.deepcell -m "fix tax rate" OLD NEW
+      deepcell replace model.deepcell --replace-all "old" "new"
+      echo '{"old_string":"...","new_string":"..."}' | deepcell replace model.deepcell --batch -
+
+    \b
+    A literal that starts with '-' must come after '--':
+      deepcell replace model.deepcell -- "-166667" "-200000"
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    title, rationale = write_message()
+    do_replace(
+        ctx, slug, filename, old_string, new_string, batch_file, replace_all,
+        revision, title, rationale,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Implementation — shared with the deprecated `edit --replace` alias
+# ---------------------------------------------------------------------------
+
+
+def format_replace_conflict(payload: dict) -> str:
+    """Render the structured 409 detail from the :replace endpoint."""
+    reason = payload.get("reason", "conflict")
+    lines: list[str] = []
+    if reason == "not_found":
+        lines.append("old_string not found in file.")
+        nearest = payload.get("nearest_match")
+        if nearest:
+            nearest_lines = payload.get("nearest_lines") or []
+            where = (
+                f" (lines {nearest_lines[0]}-{nearest_lines[1]})"
+                if len(nearest_lines) == 2
+                else ""
+            )
+            lines.append(f"Nearest match in file{where}:")
+            lines.append(nearest)
+    elif reason == "ambiguous":
+        lines.append(f"old_string found {payload.get('count', '?')} times.")
+        spelling = payload.get("matched_spelling")
+        if spelling and spelling != payload.get("old_string"):
+            lines.append("Matched spelling in the file (what --replace-all would rewrite):")
+            lines.append(spelling)
+    elif reason == "stale_revision":
+        current = payload.get("current_revision")
+        lines.append(
+            f"File changed since your revision (current: {current})."
+            if current
+            else "File changed since your revision."
+        )
+    hint = payload.get("hint")
+    if hint:
+        lines.append(f"Hint: {hint}")
+    return "\n".join(lines)
+
+
+def do_replace(
+    ctx: Ctx,
+    slug: str,
+    filename: str,
+    old_string_arg: str | None,
+    new_string_arg: str | None,
+    batch_file: str | None,
+    replace_all: bool,
+    revision: str | None,
+    title: str | None = None,
+    rationale: str | None = None,
+    *,
+    usage: str = "deepcell replace FILE OLD NEW",
+) -> None:
+    """Execute string-replacement editing on a workspace file (server-side).
+
+    Matching happens on the server (POST /files:replace, filename in the
+    body) so it can canonicalize old_string through the same normalization
+    pipeline the write path uses — a stale-but-semantically-current
+    old_string still matches. Against an older server without that route the
+    command falls back to the legacy client-side match-and-upload flow.
+
+    ``usage`` names the invocation form in argument errors, so the deprecated
+    ``edit --replace`` alias still teaches its own spelling.
+    """
+    from deepcell_cli.errors import APIError
+
+    # Parse old_string / new_string
+    if batch_file:
+        raw = read_batch_payload(batch_file)
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise click.UsageError(f"Batch JSON does not parse — {exc}") from exc
+        if not isinstance(payload, dict) or "old_string" not in payload or "new_string" not in payload:
+            raise click.UsageError(
+                'Replace --batch JSON must be {"old_string": "...", "new_string": "..."}.'
+            )
+        old_string: str = payload["old_string"]
+        new_string: str = payload["new_string"]
+    elif old_string_arg is not None and new_string_arg is not None:
+        old_string = old_string_arg
+        new_string = new_string_arg
+    else:
+        batch_form = usage.rsplit(" OLD NEW", 1)[0]
+        raise click.UsageError(
+            f"Replace requires two positional args: {usage}\n"
+            "or JSON via stdin: echo '{\"old_string\":\"...\",\"new_string\":\"...\"}' "
+            f"| {batch_form} --batch -"
+        )
+
+    body: dict = {
+        "filename": filename,
+        "old_string": old_string,
+        "new_string": new_string,
+        "replace_all": replace_all,
+    }
+    if revision:
+        body["expected_revision"] = revision
+    if title:
+        body["title"] = title
+    if rationale:
+        body["rationale"] = rationale
+
+    try:
+        result = ctx.client.post(f"/workspaces/{slug}/files:replace", json=body)
+    except APIError as exc:
+        if exc.status_code == 404 and exc.detail == "Not Found":
+            # The framework-default 404 means the files:replace route does not
+            # exist (older server) — a missing *file* gets a specific message.
+            echo_warning(
+                "Server predates server-side replace — falling back to "
+                "client-side matching (upgrade the server for "
+                "canonicalization-aware matching)."
+            )
+            do_replace_legacy(
+                ctx, slug, filename, old_string, new_string, replace_all,
+                title, rationale, revision,
+            )
+            return
+        if exc.status_code == 409 and isinstance(exc.payload, dict):
+            raise click.ClickException(format_replace_conflict(exc.payload)) from exc
+        raise
+
+    output_mutation(result, ctx.fmt, plain_key="commit_sha")
+
+    errors = echo_validation(result)
+
+    if isinstance(result, dict):
+        tier = result.get("match_tier")
+        if tier and tier != "exact":
+            echo_warning(
+                f"old_string matched via the {tier} tier — the bytes rewritten "
+                "in the file differ from the old_string you passed"
+            )
+
+    replaced = result.get("replacements", 1) if isinstance(result, dict) else 1
+    if errors:
+        echo_warning(
+            f"{replaced} replacement(s) applied but the document now has "
+            f"{len(errors)} validation error(s) — fix the errors above"
+        )
+        raise click.exceptions.Exit(1)
+    echo_success(f"{replaced} replacement(s) applied")
+
+
+def do_replace_legacy(
+    ctx: Ctx,
+    slug: str,
+    filename: str,
+    old_string: str,
+    new_string: str,
+    replace_all: bool,
+    title: str | None,
+    rationale: str | None,
+    revision: str | None = None,
+) -> None:
+    """Client-side match-and-upload flow for servers without files:replace.
+
+    Exact + whitespace-tolerant matching only (no canonicalization tier —
+    that needs the server's normalization pipeline).
+
+    This is a read-modify-write across two round trips, so it carries the
+    lost-update window the server-side route does not: the revision of the
+    bytes it matched against rides back as ``expected_revision``, and the
+    caller's own ``--revision`` (if any) takes precedence over it.
+    """
+    from deepcell_cli.xml_replace import (
+        find_whitespace_tolerant_match,
+        normalize_new_string_indentation,
+    )
+
+    data, read_revision = ctx.client.get_with_revision(
+        f"/workspaces/{slug}/files/{filename}"
+    )
+    if isinstance(data, dict) and "content" in data:
+        content: str = data["content"]
+    else:
+        raise click.ClickException(f"Could not read file content for '{filename}'.")
+
+    count = content.count(old_string)
+    if count == 1:
+        new_content = content.replace(old_string, new_string, 1)
+    elif count > 1:
+        if replace_all:
+            new_content = content.replace(old_string, new_string)
+        else:
+            raise click.ClickException(
+                f"old_string found {count} times. Use --replace-all to replace all occurrences."
+            )
+    else:
+        actual_old = find_whitespace_tolerant_match(content, old_string)
+        if actual_old is None:
+            raise click.ClickException(
+                "old_string not found in file (exact and whitespace-tolerant search)."
+            )
+        adjusted_new = normalize_new_string_indentation(actual_old, old_string, new_string)
+        new_content = content.replace(actual_old, adjusted_new, 1)
+
+    from deepcell_cli.errors import APIError
+    from deepcell_cli.revision import raise_if_stale, write_body
+
+    # `commit_message` as well as the pair, on this path only. This runs when
+    # the server is old enough to lack `files:replace`, which means it is also
+    # old enough to lack `title`/`rationale` on the write body — and pydantic
+    # drops an unknown field silently, so the reason would vanish with no
+    # error. A server that understands both prefers the pair and keeps this as
+    # a `Summary` trailer, so sending it costs nothing there.
+    body = write_body(
+        new_content,
+        revision or read_revision,
+        title=title,
+        rationale=rationale,
+        commit_message=rationale or title,
+    )
+    try:
+        result = ctx.client.post(f"/workspaces/{slug}/files/{filename}", json=body)
+    except APIError as exc:
+        raise_if_stale(exc, filename=filename)
+        raise
+    output_mutation(result, ctx.fmt, plain_key="commit_sha")
+
+    errors = echo_validation(result)
+
+    replaced = count if (count > 1 and replace_all) else 1
+    if errors:
+        echo_warning(
+            f"{replaced} replacement(s) applied but the document now has "
+            f"{len(errors)} validation error(s) — fix the errors above"
+        )
+        raise click.exceptions.Exit(1)
+    echo_success(f"{replaced} replacement(s) applied")