deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/rules.py

@@ -0,0 +1,206 @@
+"""``deepcell rules`` — invariants scoped to the selected work shape.
+
+A sibling of ``deepcell guide``, split out because rules must be selected for
+the work shape before writing and verified before done. See
+docs/cli-agent-surface.md §4.
+
+The listing leads with enforcement rather than description: what an agent needs
+from the index is which invariants a linter will catch for it, and which it
+must verify itself. Lint findings print the id of the rule they enforce, so
+``rules R2`` is the other half of a failure the agent has already hit.
+"""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import output, print_plain
+
+
+def _format_enforcement(rule: dict) -> str:
+    """One-line enforcement summary for the listing."""
+    if rule.get("enforcement") != "lint":
+        return "review"
+    codes = ", ".join(rule.get("lint") or [])
+    command = rule.get("command")
+    return f"{command} — {codes}" if command else codes
+
+
+def _format_scope(rule: dict) -> str:
+    scopes = list(rule.get("surfaces") or [])
+    if rule.get("pack"):
+        scopes.append(f"pack:{rule['pack']}")
+    return ",".join(scopes) if scopes else "universal"
+
+
+def _selection_notes(
+    rules: list[dict], *, surfaces: str | None, pack: str | None
+) -> list[str]:
+    """What a `--surfaces` / `--pack` selection did NOT add, one line each.
+
+    Computed from the rows rather than asked of the server: every row carries
+    its `surfaces` and `pack`, so a selected surface that no row names, or a
+    pack no row belongs to, is visible in the answer already. Nothing is
+    said when the selection worked — the scope column shows that.
+    """
+    notes: list[str] = []
+    selected = [s.strip() for s in (surfaces or "").split(",") if s.strip()]
+    if selected:
+        covered = {s for r in rules for s in (r.get("surfaces") or [])}
+        missing = [s for s in selected if s not in covered]
+        if missing:
+            rest = (
+                "universal rules follow"
+                if len(missing) == len(selected)
+                else "universal rules and the other selected surfaces' rules follow"
+            )
+            notes.append(f"No {'/'.join(missing)}-specific rules; {rest}.")
+    if pack and not any(r.get("pack") == pack for r in rules):
+        notes.append(
+            f"The {pack} pack contributes no rules to this selection — a pack "
+            "rule also needs its surface selected; `deepcell rules --all` "
+            "shows every rule's scope."
+        )
+    return notes
+
+
+@click.command()
+@click.argument("rule_id", required=False)
+@click.option(
+    "--pack",
+    default=None,
+    help="Add this domain pack's rules when their selected surface applies.",
+)
+@click.option(
+    "--surfaces",
+    default=None,
+    metavar="LIST",
+    help="Comma-separated selected surfaces: reasoning,spreadsheet,document,deck. "
+    "Omit for universal rules only.",
+)
+@click.option(
+    "--all",
+    "all_rules",
+    is_flag=True,
+    help="Every rule, whatever work shape it applies to. Overrides "
+    "--surfaces/--pack.",
+)
+@click.option(
+    "--full",
+    is_flag=True,
+    help="Print every applicable rule in full, not just the index — one call, "
+    "no per-rule round trips.",
+)
+@pass_ctx
+def rules(
+    ctx: Ctx,
+    rule_id: str | None,
+    pack: str | None,
+    surfaces: str | None,
+    all_rules: bool,
+    full: bool,
+) -> None:
+    """The invariants applicable to a .deepcell work shape.
+
+    \b
+    Universal rules:  deepcell rules
+    For a work shape: deepcell rules --surfaces reasoning,document
+    Finance grid:     deepcell rules --surfaces spreadsheet --pack finance
+    Every rule:       deepcell rules --all
+    Read one:         deepcell rules R2
+
+    Rule ids are stable — a lint finding cites the rule it enforces, so the id
+    printed by a failure is the argument to pass here.
+    """
+    if rule_id:
+        if pack or surfaces or all_rules:
+            raise click.UsageError(
+                "--all/--surfaces/--pack select a rulebook; omit them when "
+                "reading one id."
+            )
+        data = ctx.client.get(f"/rules/{rule_id}")
+        if ctx.fmt == "json":
+            output(data, ctx.fmt)
+            return
+        # A non-dict here means the API returned something this command cannot
+        # read; print it rather than crashing on .get().
+        if not isinstance(data, dict):
+            print_plain(str(data))
+            return
+        body = data.get("body", "")
+        header = f"{data.get('id')}. {data.get('title')}"
+        lines = [header, "=" * len(header), ""]
+        lines.append(f"Enforcement: {_format_enforcement(data)}")
+        lines.append(f"Applies to:  {_format_scope(data)}")
+        see_also = data.get("see_also") or []
+        if see_also:
+            lines.append(f"See also:    {' · '.join(see_also)}")
+        lines += ["", str(body).rstrip()]
+        print_plain("\n".join(lines))
+        return
+
+    params = {
+        key: value
+        for key, value in {
+            "surfaces": None if all_rules else surfaces,
+            "pack": None if all_rules else pack,
+            "all": "true" if all_rules else None,
+        }.items()
+        if value
+    }
+    data = ctx.client.get("/rules", params=params or None)
+    rule_list = data.get("rules", []) if isinstance(data, dict) else data
+
+    if ctx.fmt == "json":
+        output(data, ctx.fmt)
+        return
+
+    # Say when a selection added nothing, before printing what it did not
+    # narrow. `--surfaces deck` returns exactly the universal set — no rule is
+    # deck-scoped — and `--pack research` returns it too, and both printed
+    # that set with nothing on screen saying the selector had no effect. A
+    # reader takes silence as "these are the deck rules".
+    notes = (
+        _selection_notes(rule_list, surfaces=surfaces, pack=pack)
+        if isinstance(rule_list, list) and not all_rules
+        else []
+    )
+
+    # --full is the applicable rulebook. It is a flag rather than the default
+    # because the default has to match what `--help` promises and what
+    # `deepcell guide` does with no argument: print an index.
+    if full and isinstance(data, dict) and data.get("markdown"):
+        print_plain("\n".join(notes + [""] + [data["markdown"]]) if notes else data["markdown"])
+        return
+
+    if not isinstance(rule_list, list) or not rule_list:
+        # No rules to tabulate — say so plainly rather than rendering the raw
+        # envelope as a one-row table, which is what `output()` would do.
+        print_plain(
+            "No rules available. The rule library is empty or could not be "
+            "read on the server."
+        )
+        return
+
+    id_width = max(len(str(r.get("id", ""))) for r in rule_list)
+    title_width = max(len(str(r.get("title", ""))) for r in rule_list)
+    lines = notes + [""] if notes else []
+    lines += [
+        f"{str(r.get('id', '')):<{id_width}}  {str(r.get('title', '')):<{title_width}}  "
+        f"{_format_scope(r):<30}  {_format_enforcement(r)}".rstrip()
+        for r in rule_list
+    ]
+    unenforced = [r["id"] for r in rule_list if r.get("enforcement") != "lint"]
+    lines += ["", "Read a rule:          deepcell rules <id>"]
+    if not all_rules:
+        # Without this the listing is silently partial: a bare call shows the
+        # universal rules only, and nothing on screen says the rest exist.
+        lines[-1:] = [
+            "Select work surfaces: deepcell rules --surfaces reasoning,document",
+            "Every rule:           deepcell rules --all",
+            "Read a rule:          deepcell rules <id>",
+        ]
+    if unenforced:
+        lines.append(f"Nothing lints {', '.join(unenforced)} — verify these yourself.")
+    print_plain("\n".join(lines))

deepcell_cli/commands/share.py

@@ -0,0 +1,186 @@
+"""Share-link commands: create, list, revoke.
+
+Thin pass-through to the sharing router (``/workspaces/{slug}/shares`` +
+``DELETE .../shares/{id}``). ``share create`` prints the frontend viewer URL
+so a model can be opened in the browser by anyone with the link — including
+straight from an anonymous session (view-only links, server-enforced expiry).
+"""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.config import frontend_base_url, is_anonymous_session
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_success, output
+
+
+@click.group()
+def share() -> None:
+    """Create and manage browser share links for .deepcell files.
+
+    A share link gives anyone with the URL access to one file in the web
+    viewer — view-only by default, no sign-in needed to look. View-only links
+    can be created without an account (they expire after a few days); edit
+    links and password protection require one (`deepcell login`).
+    """
+
+
+@share.command("create")
+@click.argument("filename")
+@click.option(
+    "--permission",
+    type=click.Choice(["view", "edit"]),
+    default="view",
+    show_default=True,
+    help="Access level for the link. Edit links require an account.",
+)
+@click.option(
+    "--expires-days",
+    type=click.IntRange(1, 365),
+    default=None,
+    help=(
+        "Days until the link expires. Every link expires; omit this to take the "
+        "server default (90 days, or 7 for a password-less --permission edit "
+        "link). Larger values are clamped to that cap."
+    ),
+)
+@click.option(
+    "--expires-hours",
+    type=click.IntRange(1, 365 * 24),
+    default=None,
+    help=(
+        "The same lifetime in hours, for a link that should outlive a meeting "
+        "and not a day. Clamped against the same caps as --expires-days; pass "
+        "one or the other, not both."
+    ),
+)
+@click.option("--password", default=None, help="Password-protect the link (account required).")
+@click.option("--label", default=None, help="Label to recognize the link in `share list`.")
+@pass_ctx
+def share_create(
+    ctx: Ctx,
+    filename: str,
+    permission: str,
+    expires_days: int | None,
+    expires_hours: int | None,
+    password: str | None,
+    label: str | None,
+) -> None:
+    """Create a share link for FILENAME and print its viewer URL."""
+    slug = ctx.require_workspace()
+    if expires_days is not None and expires_hours is not None:
+        # Not a precedence rule: two stated lifetimes mean only one of them is
+        # what the caller meant, and silently preferring either hands out a
+        # capability that lives longer or shorter than they asked for.
+        raise click.UsageError(
+            "Pass --expires-days or --expires-hours, not both — they are the "
+            "same lifetime in different units."
+        )
+    body: dict = {"filename": filename, "permission": permission}
+    if expires_days is not None:
+        body["expires_in_days"] = expires_days
+    if expires_hours is not None:
+        body["expires_in_hours"] = expires_hours
+    if password:
+        body["password"] = password
+    if label:
+        body["label"] = label
+    row = ctx.client.post(f"/workspaces/{slug}/shares", json=body)
+
+    url = f"{frontend_base_url()}/share/{row['share_token']}"
+    if ctx.fmt == "json":
+        # Structured consumers (MCP forces json) need token/id/url as data,
+        # not scraped out of the pretty two-line output below.
+        output({**row, "url": url}, "json")
+        return
+
+    click.echo(url)
+    details = [f"Permission: {row['permission']}"]
+    if row.get("expires_at"):
+        details.append(f"Expires: {row['expires_at']}")
+    if row.get("has_password"):
+        details.append("Password-protected")
+    if row.get("id"):
+        # The id is the only input `share revoke` accepts — without it here,
+        # revoking requires a `share list -f json` round-trip.
+        details.append(f"Id: {row['id']}")
+    click.echo(" · ".join(details))
+    if not is_anonymous_session():
+        # The share link is for handing off; the owner's own browsing should
+        # go through the authenticated workbench (stderr keeps stdout to the
+        # URL + details lines only, so `head -1` still yields the URL).
+        click.echo(
+            f"For your own editing, `deepcell viewer {filename}` opens your workbench.",
+            err=True,
+        )
+
+
+def _share_row_plain(row: dict) -> str:
+    """One scannable line per link: id, permission, filename, URL, annotations.
+
+    The generic list formatter used to reduce rows to bare filenames, leaving
+    plain mode with no path to a revocable id or a reconstructable URL.
+    """
+    parts = [
+        str(row.get("id", "")),
+        str(row.get("permission", "")),
+        str(row.get("filename", "")),
+        f"{frontend_base_url()}/share/{row.get('share_token', '')}",
+    ]
+    notes: list[str] = []
+    if row.get("label"):
+        notes.append(f'label "{row["label"]}"')
+    if row.get("expires_at"):
+        notes.append(f"expires {row['expires_at']}")
+    if row.get("has_password"):
+        notes.append("password")
+    if not row.get("is_active", True):
+        notes.append("revoked")
+    if row.get("view_count"):
+        notes.append(f"{row['view_count']} views")
+    line = "  ".join(p for p in parts if p)
+    if notes:
+        line += f"  ({', '.join(notes)})"
+    return line
+
+
+def _share_row_with_url(row: dict) -> dict:
+    """Add the same usable viewer URL exposed by plain and create output."""
+    token = row.get("share_token")
+    if not token:
+        return row
+    return {**row, "url": f"{frontend_base_url()}/share/{token}"}
+
+
+@share.command("list")
+@click.option("--file", "filename", default=None, help="Only links for this file.")
+@pass_ctx
+def share_list(ctx: Ctx, filename: str | None) -> None:
+    """List active share links in the workspace."""
+    slug = ctx.require_workspace()
+    params = {"filename": filename} if filename else None
+    data = ctx.client.get(f"/workspaces/{slug}/shares", params=params)
+    if isinstance(data, list):
+        data = [
+            _share_row_with_url(row) if isinstance(row, dict) else row
+            for row in data
+        ]
+    if ctx.fmt == "plain" and isinstance(data, list):
+        if not data:
+            click.echo("(no share links)")
+        for row in data:
+            if isinstance(row, dict):
+                click.echo(_share_row_plain(row))
+        return
+    output(data, ctx.fmt)
+
+
+@share.command("revoke")
+@click.argument("share_id")
+@pass_ctx
+def share_revoke(ctx: Ctx, share_id: str) -> None:
+    """Revoke a share link by its id (see `share list`)."""
+    slug = ctx.require_workspace()
+    ctx.client.delete(f"/workspaces/{slug}/shares/{share_id}")
+    echo_success("Share link revoked.")