fruxon 0.5.2__tar.gz → 0.5.4__tar.gz

{fruxon-0.5.2 → fruxon-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fruxon
-Version: 0.5.2
+Version: 0.5.4
 Summary: The Fruxon SDK is a lightweight Python client for integrating with the Fruxon platform.
 Project-URL: bugs, https://github.com/fruxon-ai/fruxon-sdk/issues
 Project-URL: changelog, https://github.com/fruxon-ai/fruxon-sdk/blob/main/HISTORY.md
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
+Requires-Dist: keyring>=24.0
 Requires-Dist: typer>=0.13
 Provides-Extra: test
 Requires-Dist: coverage; extra == 'test'

{fruxon-0.5.2 → fruxon-0.5.4}/pyproject.toml

@@ -69,6 +69,12 @@ dependencies = [
   # ``--help`` invocation when paired with click 8.2+, which other
   # packages routinely pull in. Floor here protects users from that drift.
   "typer>=0.13",
+  # OS-keychain backed credential storage for ``fruxon login`` — macOS
+  # Keychain, libsecret/KWallet on Linux, Credential Manager on Windows.
+  # We use it via thin shims around the same shape we already write to
+  # ``~/.fruxon/credentials`` so callers behind a corp policy that
+  # disables the keyring fall back transparently to the file path.
+  "keyring>=24.0",
 ]
 requires-python = ">= 3.10"
 

{fruxon-0.5.2 → fruxon-0.5.4}/src/fruxon/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.2'
-__version_tuple__ = version_tuple = (0, 5, 2)
+__version__ = version = '0.5.4'
+__version_tuple__ = version_tuple = (0, 5, 4)
 
 __commit_id__ = commit_id = None

fruxon-0.5.4/src/fruxon/cli/__init__.py

@@ -0,0 +1,236 @@
+"""Fruxon CLI · entry point.
+
+The Typer ``app`` is the singleton every command registers against. Each
+command lives in its own module under ``fruxon.cli.*`` and imports the
+shared ``app`` from here. Importing those modules at package load is what
+binds their ``@app.command()`` decorators to ``app``.
+
+The packaging entry point points at ``fruxon.cli:app`` (see
+``pyproject.toml`` ``[project.scripts]``).
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import sys
+from typing import Annotated
+
+import typer
+from typer.core import TyperGroup
+
+from fruxon import credentials
+from fruxon.ui import (
+    dashboard_url,
+    get_version,
+    is_agent_mode,
+    maybe_print_update_notice,
+    print_banner,
+    print_welcome,
+    say_err,
+)
+
+
+class _FruxonTyperGroup(TyperGroup):
+    """Branded replacement for Typer's stock ``no such command`` error.
+
+    Click's default renders the failure as a bordered ASCII box that
+    looks nothing like the rest of Fruxon's UI:
+
+        ╭─ Error ──────────────────────────────────╮
+        │ No such command 'foobar'.                │
+        ╰──────────────────────────────────────────╯
+
+    We override ``get_command`` to catch the miss before Click raises,
+    print the Fruxon-styled ``✗`` line + a "did you mean?" suggestion
+    via :mod:`difflib`, then exit. Same exit code (2 — Click's
+    ``UsageError.exit_code``) so scripts checking ``$?`` see the same
+    signal.
+    """
+
+    def get_command(self, ctx, cmd_name):
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd is not None:
+            return cmd
+
+        # Branded error path. Build a "did you mean?" suggestion from
+        # the registered subcommand names — same difflib pattern we use
+        # for agent IDs so the UX feels consistent.
+        import difflib
+
+        candidates = list(self.commands.keys())
+        suggestions = difflib.get_close_matches(cmd_name, candidates, n=1, cutoff=0.6)
+        if suggestions:
+            hint = (
+                f"Did you mean [bold]fruxon {suggestions[0]}[/bold]?  "
+                "Run [bold]fruxon --help[/bold] for the full command list."
+            )
+        else:
+            hint = "Run [bold]fruxon --help[/bold] for the full command list."
+        say_err(f"Unknown command [bold]{cmd_name}[/bold].", hint=hint)
+        ctx.exit(2)
+        return None  # unreachable but keeps the type checker happy
+
+
+# Print the "newer fruxon is available" notice (if any) at the tail of
+# every invocation. Registered at CLI load so it fires regardless of
+# which subcommand ran, including --help and error exits. The notifier
+# already swallows every exception internally — atexit handlers must
+# never raise, so this is the right place.
+atexit.register(maybe_print_update_notice)
+
+app = typer.Typer(
+    help="Fruxon CLI · tools for working with the Fruxon platform.",
+    pretty_exceptions_enable=False,
+    cls=_FruxonTyperGroup,
+)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option("--version", "-V", help="Print the CLI version and exit."),
+    ] = False,
+):
+    """Fruxon CLI · agent execution, export, and platform tooling.
+
+    Credentials are resolved in this order (first non-empty wins):
+      1. Explicit flags (--api-key / --org / --base-url)
+      2. Environment variables (FRUXON_API_KEY / FRUXON_ORG / FRUXON_BASE_URL)
+      3. The credentials file managed by `fruxon login` (~/.fruxon/credentials)
+
+    Environment:
+      FRUXON_API_KEY        Default API key for `fruxon run`.
+      FRUXON_ORG            Default organization.
+      FRUXON_BASE_URL       Override the API base URL (staging / self-hosted).
+      FRUXON_CONFIG_DIR     Override the credentials directory (default ~/.fruxon).
+      FRUXON_DASHBOARD_URL  Where `fruxon login` points the browser.
+      FRUXON_GLYPH          Override the brand glyph (default: ✻).
+      FRUXON_BRAND_COLOR    Override the brand color (e.g. `#7c5cff`, `cyan`).
+      FRUXON_NO_BANNER=1    Suppress all branding chrome.
+      FRUXON_AGENT_MODE=1   Optimize for AI-agent / script consumption — no
+                            banner, JSON manifest on bare invocation. Also
+                            auto-detected from CLAUDECODE=1 / CI=1.
+      NO_COLOR=1            Standard convention — disables all color output.
+    """
+    if version:
+        print_banner()
+        raise typer.Exit()
+
+    if ctx.invoked_subcommand is not None:
+        return
+
+    # Bare ``fruxon`` — the highest-leverage moment in the whole UX.
+    # First-run users decide whether to keep going based on what
+    # appears here; AI agents pattern-match on it to decide how to
+    # use the tool. We serve two surfaces from the same entrypoint:
+    #
+    # * Agent mode (Claude Code, CI, ``FRUXON_AGENT_MODE=1``) →
+    #   single-line JSON manifest on stdout describing state +
+    #   next-step commands. No banner, no chrome. An LLM reads
+    #   this once and is fluent in Fruxon.
+    # * Human mode → branded welcome with state-aware CTAs.
+    #   Branching on signed-in vs not surfaces the right next door:
+    #   first-time users see "sign in" before everything else;
+    #   signed-in users see the productive paths instead.
+    creds = credentials.load()
+    signed_in = bool(credentials.resolve_api_key(None))
+
+    if is_agent_mode():
+        _print_agent_manifest(creds=creds, signed_in=signed_in)
+        raise typer.Exit()
+
+    _print_human_welcome(creds=creds, signed_in=signed_in)
+    raise typer.Exit()
+
+
+def _print_human_welcome(*, creds: credentials.StoredCredentials, signed_in: bool) -> None:
+    """Branded welcome for a person sitting at the terminal.
+
+    Tone target: Claude Code's startup card — one tagline, two
+    state-aware CTAs, one universal escape hatch (``--help``).
+    Deliberately NOT dumping the Typer commands table — that's
+    a wall of duplicated info one keystroke away via ``--help``.
+    """
+    tagline = "Run, build, and orchestrate AI agents from your terminal."
+
+    lines: list[str] = [tagline, ""]
+    if signed_in:
+        org_label = f"org [bold]{creds.org}[/bold]" if creds.org else "no default org"
+        lines.append(f"[green]✓[/green] Signed in · {org_label}")
+        lines.append("")
+        lines.append("Try:   [bold]fruxon agents list[/bold]    — browse what's deployed")
+        lines.append("       [bold]fruxon run[/bold] <agent>    — execute one")
+        lines.append("       [bold]fruxon chat[/bold] <agent>   — open an interactive REPL")
+    else:
+        lines.append("[yellow]›[/yellow] Not signed in")
+        lines.append("")
+        lines.append("Sign in:       [bold]fruxon login[/bold]")
+        lines.append(f"No account?    Visit [link]{dashboard_url()}[/link]")
+
+    lines.append("")
+    lines.append("All commands:  [bold]fruxon --help[/bold]")
+    lines.append("Diagnostics:   [bold]fruxon doctor[/bold]")
+
+    print_welcome(tips=lines)
+
+
+def _print_agent_manifest(*, creds: credentials.StoredCredentials, signed_in: bool) -> None:
+    """One-line JSON manifest for AI agents and scripts.
+
+    The shape is intentionally tiny and stable: name, version,
+    auth state, and a ``next`` object pointing at the commands an
+    LLM should reach for. The goal is "an LLM reads this once and
+    knows what to do" — not a full schema dump (that's the future
+    ``fruxon describe``).
+
+    Stdout, not stderr — agents expect their parseable signal on
+    stdout. JSON one-liner so it composes cleanly with ``| jq``.
+    """
+    manifest = {
+        "name": "fruxon",
+        "version": get_version(),
+        "signed_in": signed_in,
+        "org": creds.org if signed_in else None,
+        "next": (
+            {
+                "agents": "fruxon agents list --output json",
+                "run": "fruxon run <agent> -p key=value --output json",
+                "chat": "fruxon chat <agent>",
+                "trace": "fruxon trace <agent> <record-id> --output json",
+                "help": "fruxon --help",
+            }
+            if signed_in
+            else {
+                "login": "fruxon login --api-key <KEY>",
+                "dashboard": dashboard_url(),
+                "help": "fruxon --help",
+            }
+        ),
+    }
+    sys.stdout.write(json.dumps(manifest) + "\n")
+    sys.stdout.flush()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Command registration
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Importing the command modules below executes their ``@app.command()`` and
+# ``app.add_typer(...)`` calls, wiring every subcommand into the singleton
+# above. The order doesn't matter for correctness — only for the order they
+# show up in ``fruxon --help``.
+
+from fruxon.cli import agents as _agents  # noqa: E402, F401
+from fruxon.cli import auth as _auth  # noqa: E402, F401
+from fruxon.cli import chat as _chat  # noqa: E402, F401
+from fruxon.cli import config as _config  # noqa: E402, F401
+from fruxon.cli import doctor as _doctor  # noqa: E402, F401
+from fruxon.cli import export as _export  # noqa: E402, F401
+from fruxon.cli import run as _run  # noqa: E402, F401
+from fruxon.cli import trace as _trace  # noqa: E402, F401
+
+if __name__ == "__main__":
+    app()

{fruxon-0.5.2 → fruxon-0.5.4}/src/fruxon/cli/agents.py

@@ -18,7 +18,15 @@ from fruxon import credentials
 from fruxon.cli import app
 from fruxon.exceptions import FruxonError
 from fruxon.fruxon import Agent, FruxonClient
-from fruxon.ui import print_banner, say_err, say_info, say_ok, stderr
+from fruxon.ui import (
+    dashboard_url,
+    print_banner,
+    resolve_output_format,
+    say_err,
+    say_info,
+    say_ok,
+    stderr,
+)
 
 agents_app = typer.Typer(
     help="Browse and inspect agents in your org.",
@@ -73,13 +81,17 @@ def agents_list(
     ] = None,
     base_url: Annotated[str | None, typer.Option("--base-url", help="API base URL override.")] = None,
     output: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--output",
             "-o",
-            help="Output format: table (default · humans), json (machines), id (one ID per line, pipe-safe).",
+            help=(
+                "Output format: table (default for humans), json (machines, default in "
+                "agent mode), id (one ID per line, pipe-safe). Under FRUXON_AGENT_MODE / "
+                "CLAUDECODE / CI the implicit default flips to json."
+            ),
         ),
-    ] = "table",
+    ] = None,
     disabled: Annotated[
         bool,
         typer.Option(
@@ -99,6 +111,7 @@ def agents_list(
         fruxon agents list --output json
         fruxon agents list --output id | xargs -n1 fruxon run
     """
+    output = resolve_output_format(output, human_default="table", agent_default="json")
     if output not in {"table", "json", "id"}:
         say_err(
             f"Unknown output format: [bold]{output}[/bold]",
@@ -120,16 +133,44 @@ def agents_list(
         say_err(str(e), hint=_hint_for_list_error(e))
         raise typer.Exit(code=1) from e
 
-    if not disabled:
-        agents = [a for a in agents if a.enabled]
-
-    if not agents:
+    # Distinguish the two "empty" cases so the hint actually fits the
+    # situation. A first-time user with zero agents in their org needs
+    # to be pointed at the dashboard; a user whose agents are all
+    # disabled needs to know ``--all`` exists. Same flat "No agents
+    # to show" message used to swallow both — useless in both cases.
+    all_agents = agents
+    visible_agents = all_agents if disabled else [a for a in all_agents if a.enabled]
+
+    if not visible_agents:
+        if not all_agents:
+            # Truly empty org — onboarding moment, not a filter quirk.
+            # JSON callers get an empty array (already returned above
+            # in the output branches below) so this say_info is purely
+            # for the human-facing path.
+            if output == "json":
+                print("[]")
+                return
+            if output == "id":
+                return
+            say_info(
+                "No agents deployed in this org yet.",
+                hint=f"Create one in the dashboard: [link]{dashboard_url()}[/link]",
+            )
+            return
+        # Some agents exist but every one is disabled.
+        if output == "json":
+            print("[]")
+            return
+        if output == "id":
+            return
         say_info(
-            "No agents to show.",
-            hint="Try [bold]--all[/bold] to include disabled agents, or create one in the dashboard.",
+            "All agents in this org are disabled.",
+            hint="Use [bold]--all[/bold] to include disabled agents.",
         )
         return
 
+    agents = visible_agents
+
     if output == "id":
         # One ID per line on stdout for trivial shell composition.
         for a in agents:
@@ -155,21 +196,37 @@ def agents_get(
         typer.Option("--api-key", "-k", envvar="FRUXON_API_KEY", help="API key override."),
     ] = None,
     base_url: Annotated[str | None, typer.Option("--base-url", help="API base URL override.")] = None,
-    json_output: Annotated[
-        bool,
-        typer.Option("--json", help="Output the agent as JSON instead of human-readable rows."),
-    ] = False,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help=(
+                "Output format: text (default for humans), json (machines, default in "
+                "agent mode). Under FRUXON_AGENT_MODE / CLAUDECODE / CI the implicit "
+                "default flips to json."
+            ),
+        ),
+    ] = None,
 ):
     """Show one agent's details.
 
     Examples:
         fruxon agents get support-agent
-        fruxon agents get support-agent --json
+        fruxon agents get support-agent --output json
     """
+    output = resolve_output_format(output, human_default="text", agent_default="json")
+    if output not in {"text", "json"}:
+        say_err(
+            f"Unknown output format: [bold]{output}[/bold]",
+            hint="Valid formats: text, json.",
+        )
+        raise typer.Exit(code=1)
+
     client = _build_client(org, api_key, base_url)
 
     try:
-        if stderr.is_terminal and not json_output:
+        if stderr.is_terminal and output == "text":
             with stderr.status(f"[bold]Fetching agent [cyan]{agent}[/cyan]…[/bold]"):
                 fetched = client.get_agent(agent)
                 parameters = _fetch_parameters_safely(client, fetched)
@@ -177,10 +234,10 @@ def agents_get(
             fetched = client.get_agent(agent)
             parameters = _fetch_parameters_safely(client, fetched)
     except FruxonError as e:
-        say_err(str(e), hint=_hint_for_get_error(e, agent))
+        say_err(str(e), hint=_hint_for_get_error(e, agent, client))
         raise typer.Exit(code=1) from e
 
-    if json_output:
+    if output == "json":
         payload = _agent_to_dict(fetched)
         payload["parameters"] = parameters
         print(json.dumps(payload, indent=2))
@@ -235,6 +292,19 @@ def _fetch_parameters_safely(client: FruxonClient, fetched: Agent) -> list[str]:
 def _build_table(agents: list[Agent]):
     """Render an agent list as a rich Table.
 
+    Column shape is tuned for readability across terminal widths:
+
+    * **ID** — the must-have. ``no_wrap=True`` keeps each row on one
+      line; long IDs truncate with ``…`` rather than wrapping into
+      multi-line entries that destroy scannability.
+    * **Name** — wraps with ellipsis overflow if needed.
+    * **Status** — fixed-width, near the ID so it stays visible even
+      when narrow widths force right-side columns to shrink.
+    * **Rev** — small right-aligned column.
+    * **Tags** — last because it's the first column to truncate.
+      Hard-capped at 24 chars; previously wrapped into 4+ line entries
+      on agents with many tags, which made the table unreadable.
+
     Imported lazily so callers that don't render a table (``--output id``,
     ``--output json``) don't pay for the Table machinery.
     """
@@ -246,19 +316,37 @@ def _build_table(agents: list[Agent]):
         show_edge=False,
         pad_edge=False,
         box=None,
-        padding=(0, 2),
+        # ``padding=(0, 1)`` gives one column of gap between cells.
+        # With 5 columns the inter-cell gaps consume 4 chars total,
+        # leaving more room for content on narrow terminals (80 col
+        # ssh sessions, tmux panes, etc.) before Rich starts
+        # shrinking columns into ``…``.
+        padding=(0, 1),
     )
-    table.add_column("ID", style="bold")
-    table.add_column("Name")
-    table.add_column("Rev", justify="right", style="dim")
-    table.add_column("Tags", style="dim")
-    table.add_column("Status", justify="right")
+    # ``no_wrap=True`` on every column forces single-line-per-row.
+    # Combined with ``overflow="ellipsis"`` Rich truncates cells that
+    # overflow the column width with ``…`` instead of wrapping —
+    # critical for table scannability when an agent has many tags or
+    # a long display name.
+    #
+    # Status and Rev sit right after ID (the eye-tracking priority)
+    # and use ``no_wrap`` without a max so they always render in
+    # full. ID / Name / Tags carry ``max_width`` to bound how much
+    # space each grabs on a wide terminal and to anchor the
+    # ellipsis-truncation point on narrow ones. Old layout used to
+    # let Tags steal the row and wrap across 8 lines for agents with
+    # many tags.
+    table.add_column("ID", style="bold", no_wrap=True, overflow="ellipsis", max_width=24)
+    table.add_column("Status", justify="right", no_wrap=True)
+    table.add_column("Rev", justify="right", style="dim", no_wrap=True)
+    table.add_column("Name", no_wrap=True, overflow="ellipsis", max_width=20)
+    table.add_column("Tags", style="dim", no_wrap=True, overflow="ellipsis", max_width=22)
 
     for a in agents:
         status = "[green]enabled[/green]" if a.enabled else "[dim]disabled[/dim]"
         rev = str(a.current_revision) if a.current_revision else "—"
         tags = ", ".join(a.tags) if a.tags else "—"
-        table.add_row(a.id, a.display_name or "[dim]—[/dim]", rev, tags, status)
+        table.add_row(a.id, status, rev, a.display_name or "[dim]—[/dim]", tags)
     return table
 
 
@@ -292,10 +380,30 @@ def _hint_for_list_error(error: FruxonError) -> str | None:
     return None
 
 
-def _hint_for_get_error(error: FruxonError, agent: str) -> str | None:
+def _hint_for_get_error(error: FruxonError, agent: str, client: FruxonClient) -> str | None:
+    """Hint generator for ``agents get``.
+
+    NotFound is the high-traffic case — typos in agent IDs are common.
+    We fetch the org's agent list and use ``difflib.get_close_matches``
+    to surface a "did you mean?" suggestion. Network errors during
+    that lookup are swallowed: the user is already in an error path
+    and a second failure on top would be hostile.
+    """
     from fruxon.exceptions import NotFoundError
 
     if isinstance(error, NotFoundError):
+        import difflib
+
+        try:
+            candidates = [a.id for a in client.list_agents()]
+            suggestions = difflib.get_close_matches(agent, candidates, n=1, cutoff=0.6)
+        except Exception:
+            suggestions = []
+        if suggestions:
+            return (
+                f"Did you mean [bold]{suggestions[0]}[/bold]?  "
+                f"Run with: [bold]fruxon agents get {suggestions[0]}[/bold]"
+            )
         return (
             f"No agent matches [bold]{agent}[/bold] in this org. "
             "Try [bold]fruxon agents list[/bold] to see what's available."