sagex-cli 1.0.0__py3-none-any.whl

sagex/api/store.py

@@ -0,0 +1,52 @@
+"""Secure storage for the API key using the OS keychain (via `keyring`).
+
+Windows Credential Manager / macOS Keychain / Linux Secret Service — the key
+lives in the OS's secret store, never in a plaintext file.
+
+SAGEX_API_KEY, when set, takes precedence over the keychain. That covers CI jobs
+and headless machines with no keychain, without ever writing the key to disk.
+"""
+
+import os
+
+import keyring
+
+_SERVICE = "sagex-cli"
+_ACCOUNT = "api_key"
+ENV_VAR = "SAGEX_API_KEY"
+
+
+class KeyStoreError(Exception):
+    """The OS keychain couldn't store the key (e.g. no backend on a headless box)."""
+
+
+def key_from_env() -> str | None:
+    """The key from SAGEX_API_KEY, or None when it's unset/blank."""
+    return os.environ.get(ENV_VAR, "").strip() or None
+
+
+def get_key() -> str | None:
+    """Return the API key (env first, then keychain), or None if there isn't one."""
+    env_key = key_from_env()
+    if env_key:
+        return env_key
+    try:
+        return keyring.get_password(_SERVICE, _ACCOUNT)
+    except Exception:
+        return None
+
+
+def set_key(key: str) -> None:
+    """Store the API key in the OS keychain; KeyStoreError if there's no usable one."""
+    try:
+        keyring.set_password(_SERVICE, _ACCOUNT, key)
+    except Exception as exc:          # NoKeyringError, locked/absent Secret Service, …
+        raise KeyStoreError(str(exc)) from exc
+
+
+def delete_key() -> None:
+    """Remove the stored API key. No error if nothing was stored."""
+    try:
+        keyring.delete_password(_SERVICE, _ACCOUNT)
+    except Exception:
+        pass

sagex/app.py

@@ -0,0 +1,378 @@
+"""The sagex terminal application: layout and event wiring.
+
+Appearance lives in app.tcss; status formatting in formatting.py. This file
+focuses on WHAT widgets exist and HOW they react.
+"""
+
+import os
+
+from rich.text import Text
+from textual import events, work
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.widgets import Header, Footer, Tree, Input, Static, DirectoryTree
+
+from sagex import config, runview, shell
+from sagex.api import ApiError, build_client, resources, store
+from sagex.formatting import ACCENT, run_label, trigger_label
+from sagex.widgets.activity import ActivityLine
+from sagex.widgets.message import ChatMessage
+from sagex.widgets.run_graph import RunGraph
+from sagex.widgets.prompt_input import PromptInput
+
+
+class SagexApp(App):
+    """The whole application. Everything hangs off this one class."""
+
+    CSS_PATH = "app.tcss"                 # styling loaded from the file next to this one
+
+    BINDINGS = [
+        # Not a bare "q": you type straight into the transcript, so a letter key must
+        # never quit (e.g. keystrokes while a command runs and the prompt is hidden).
+        ("ctrl+q", "quit", "Quit"),
+        ("f2", "cycle_shell", "Shell"),
+        ("f3", "toggle_env", "Environment"),
+        ("f5", "refresh", "Refresh"),
+        ("escape", "stop_command", "Stop"),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.config = config.load()                       # persisted settings (~/.sagex)
+        self.session = shell.ShellSession(preferred=self.config.get("shell"))
+        self._busy = False                                # is a command currently running?
+        self._selected_label: str | None = None                  # the highlighted resource, if any
+        self._run_graph: RunGraph | None = None           # live graph of the running command
+        self._load_gen = 0                                # bumps on every (re)load
+        self._pending_loads: set = set()                  # branches still loading (this gen)
+
+        # Workspace = the local folder shown in the "local" environment.
+        ws = self.config.get("workspace")
+        self._workspace = ws if ws and os.path.isdir(ws) else os.getcwd()
+        # Start in the server environment if a key is stored, else local-only.
+        self._env = "server" if store.get_key() else "local"
+
+    def compose(self) -> ComposeResult:
+        """Declare WHAT is on screen, top to bottom."""
+        yield Header(show_clock=True)
+
+        # Horizontal split: resources on the left, Autobot panel on the right.
+        with Horizontal():
+            # Left: the tree, plus a one-line status bar docked at its bottom.
+            with Vertical(id="resources-panel"):
+                yield Input(                                               # local: set the folder
+                    value=self._workspace,
+                    placeholder="workspace path (relative or absolute)",
+                    id="workspace-input",
+                )
+                yield Tree("Resources", id="resources")                    # server environment
+                yield DirectoryTree(self._workspace, id="workspace-tree")  # local environment
+                yield ActivityLine(id="resources-activity")                # while branches load
+                yield Static(id="resources-status")
+
+            # Right: a terminal-style transcript. You type on the prompt line at its
+            # end; new entries are inserted above it, so the prompt always stays last.
+            with VerticalScroll(id="chat-log"):
+                yield Static(self._welcome(), id="welcome")
+                yield ActivityLine(id="command-activity")   # while a command runs
+                with Horizontal(id="prompt-row"):
+                    yield Static("❯ ", id="prompt-glyph")
+                    yield PromptInput(
+                        placeholder="Start with ! to run a command — e.g. !sagex list workflow",
+                        id="chat-input",
+                        compact=True,
+                    )
+                yield Static(id="prompt-status")
+
+        yield Footer()
+
+    @staticmethod
+    def _welcome() -> Text:
+        text = Text()
+        text.append("✻ ", style=ACCENT)
+        text.append("Welcome to sagex", style="bold")
+        text.append("  ·  Autosage in your terminal\n\n", style="bright_black")
+        text.append("Start with ", style="bright_black")
+        text.append("!", style="bold")
+        text.append(" to run a command, e.g. ", style="bright_black")
+        text.append("!sagex list workflow", style="bold")
+        text.append("  ·  Autobot chat arrives in sagex v2\n", style="bright_black")
+        text.append("Esc stops a run · ↑/↓ history · F2 shell · F3 server/local · F5 refresh · Ctrl+Q quit",
+                    style="bright_black")
+        return text
+
+    def on_mount(self) -> None:
+        """Runs once, right after the widgets exist. Good place for setup."""
+        tree = self.query_one("#resources", Tree)
+        tree.show_root = False           # show categories at the top level
+
+        # Build the categories once; a loader (re)fills each. Runs get status icons.
+        workflows = tree.root.add("Workflows")
+        scripts = tree.root.add("Scripts")
+        vault = tree.root.add("Vault")
+        runs = tree.root.add("Runs")
+        triggers = tree.root.add("Triggers")
+        tree.root.expand_all()
+
+        # (branch node, fetch function) pairs — reused by refresh.
+        self._loaders = [
+            (workflows, resources.list_workflows),
+            (scripts, resources.list_scripts),
+            (vault, resources.list_vault_resources),
+            (runs, lambda c: [run_label(*r) for r in resources.list_recent_runs(c)]),
+            (triggers, lambda c: [trigger_label(*t) for t in resources.list_triggers(c)]),
+        ]
+
+        self._refresh_prompt()           # "shell · cwd" under the prompt line
+        self._apply_env()                # show the right tree + status for the current env
+        if self._env == "server":
+            self._start_loaders()        # fetch server resources (concurrently, off-thread)
+        self.query_one("#chat-input", PromptInput).focus()   # ready to type straight away
+
+    def on_tree_node_highlighted(self, event: Tree.NodeHighlighted) -> None:
+        """Fires whenever the highlight lands on a tree node (arrows or mouse)."""
+        node = event.node
+        # A branch (category) CAN be expanded; a leaf (real item) CANNOT. A real item
+        # becomes the "context" shown under the prompt.
+        self._selected_label = None if node.allow_expand else str(node.label)
+        self._refresh_prompt()
+
+    def on_click(self, event: events.Click) -> None:
+        """A click anywhere in the transcript puts the cursor back on the prompt."""
+        log = self.query_one("#chat-log", VerticalScroll)
+        if not self._busy and event.widget is not None and log in event.widget.ancestors_with_self:
+            self.query_one("#chat-input", PromptInput).focus()
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        """Fires when the user presses Enter in an input box."""
+        if event.input.id == "workspace-input":     # the local-env path box
+            self._set_workspace(event.value)
+            return
+
+        text = event.value.strip()
+        event.input.value = ""           # clear the line either way
+        if not text:                     # ignore empty / whitespace-only lines
+            return
+        self.query_one("#chat-input", PromptInput).add_to_history(text)   # for ↑/↓ recall
+
+        if text.startswith("!"):         # "!" prefix -> run as a shell command
+            command = text[1:].strip()
+            if not command:
+                return
+            if command.lower() in ("clear", "cls"):     # UI builtin: wipe the transcript
+                log = self.query_one("#chat-log", VerticalScroll)
+                for entry in [*log.query(ChatMessage), *log.query(RunGraph)]:
+                    entry.remove()
+                return
+            self.add_message(command, "command")        # echo it, like a terminal does
+            out = self._new_output_message()            # its output streams in below
+            self._set_busy(True)
+            self.execute_command(command, out)
+        else:                            # otherwise -> agent prompt (Autobot lands in v2)
+            self.add_message(text, role="user")
+            self.add_message(
+                "Autobot isn't available in the terminal yet — it's coming in sagex v2.\n"
+                "Meanwhile, start a line with ! to run a command (try !sagex --help), "
+                f"or chat with Autobot on the web: {config.WEB_URL}/ai/autobot",
+                role="notice",
+            )
+
+    @work(thread=True)
+    def execute_command(self, command: str, out: ChatMessage) -> None:
+        """Run a shell command in a BACKGROUND THREAD, streaming its output into `out`.
+
+        This runs off the main thread, so every UI touch goes through
+        `call_from_thread`, which hands the work back to Textual's main loop.
+        """
+        def on_line(line: str) -> None:
+            event = runview.parse_event_line(line)      # progress from `sagex run workflow`
+            if event is not None:
+                self.call_from_thread(self._on_run_event, out, event)
+                return
+            self.call_from_thread(self._append_output, out, line)
+
+        try:
+            code = self.session.run_streaming(command, on_line)
+        except Exception as exc:         # e.g. the shell itself couldn't start
+            self.call_from_thread(self._append_output, out, f"Failed to run command: {exc}")
+            code = -1
+
+        self.call_from_thread(self._finish_command, out, code)
+
+    def _new_output_message(self) -> ChatMessage:
+        """(main thread) Insert an empty cmd_output entry and return it."""
+        widget = ChatMessage("", "cmd_output")
+        self._mount_entry(widget)
+        return widget
+
+    def _mount_entry(self, widget) -> None:
+        """(main thread) Insert a transcript entry above the prompt, then scroll to it."""
+        log = self.query_one("#chat-log", VerticalScroll)
+        log.mount(widget, before=self.query_one("#command-activity", ActivityLine))
+        self.call_after_refresh(log.scroll_end, animate=False)
+
+    def _set_busy(self, busy: bool) -> None:
+        """While a command runs, the prompt line gives way to the activity line — as
+        in a terminal — and comes back (with the cursor on it) when it finishes."""
+        self._busy = busy
+        activity = self.query_one("#command-activity", ActivityLine)
+        self.query_one("#prompt-row").display = not busy
+        self.query_one("#prompt-status").display = not busy
+        log = self.query_one("#chat-log", VerticalScroll)
+        if busy:
+            activity.start("Running", "esc to stop")
+            log.focus()                  # keys scroll the output instead of typing nowhere
+        else:
+            activity.stop()
+            self.query_one("#chat-input", PromptInput).focus()
+        self.call_after_refresh(log.scroll_end, animate=False)
+
+    def _on_run_event(self, out: ChatMessage, event: dict) -> None:
+        """(main thread) Create, then update, the live graph of a workflow run."""
+        if event.get("t") == "start":
+            view = runview.WorkflowRunView.from_snapshot(event.get("view") or {})
+            self._run_graph = RunGraph(view)
+            self.query_one("#chat-log", VerticalScroll).mount(self._run_graph, before=out)
+        elif self._run_graph is not None:
+            self._run_graph.apply(event)
+
+    def _append_output(self, widget: ChatMessage, line: str) -> None:
+        """(main thread) Append a line to an output entry and keep it in view."""
+        widget.append_line(line)
+        self.query_one("#chat-log", VerticalScroll).scroll_end(animate=False)
+
+    def add_message(self, text: str, role: str) -> None:
+        """Add an entry to the transcript (above the prompt) and scroll it into view."""
+        self._mount_entry(ChatMessage(text, role))
+
+    def action_stop_command(self) -> None:
+        """Esc: stop the currently running command, if any."""
+        if self._busy:
+            self.query_one("#command-activity", ActivityLine).set("Stopping", "")
+        self.session.cancel()            # kills the process; the worker then finishes
+
+    def _finish_command(self, out: ChatMessage, code: int) -> None:
+        """(main thread) A command finished: show how it ended and bring the prompt back."""
+        out.set_exit_code(code)
+        if out.is_empty:                 # a silent success leaves no empty block behind
+            out.remove()
+        if self._run_graph is not None:  # e.g. detached or crashed before a final event
+            self._run_graph.freeze()
+            self._run_graph = None
+        self._set_busy(False)
+        self._refresh_prompt()           # the working dir may have changed
+
+    def action_cycle_shell(self) -> None:
+        """F2: switch to the next installed shell (and remember the choice)."""
+        self.session.cycle_shell()
+        self.config["shell"] = self.session.shell        # persist across launches
+        config.save(self.config)
+        self._refresh_prompt()
+
+    def _refresh_prompt(self) -> None:
+        """The dim line under the prompt: 'shell · cwd', plus the highlighted resource."""
+        status = Text(self.session.prompt, style="bright_black")
+        if self._selected_label:
+            status.append("  ·  context: ", style="bright_black")
+            status.append(self._selected_label)
+        self.query_one("#prompt-status", Static).update(status)
+
+    def _start_loaders(self) -> None:
+        """(Re)load every resource branch, resetting each to 'Loading…' first."""
+        self._set_status("")             # clear any previous error
+        self._load_gen += 1
+        self._pending_loads = {id(node) for node, _ in self._loaders}
+        self.query_one("#resources-activity", ActivityLine).start("Loading resources")
+        for node, fetch in self._loaders:
+            node.remove_children()
+            node.add_leaf("Loading…")
+            self._load_branch(node, fetch, self._load_gen)
+
+    def action_refresh(self) -> None:
+        """F5: reload the current environment (also the retry for a failed load)."""
+        if self._env == "server":
+            self._start_loaders()
+        else:
+            self.query_one("#workspace-tree", DirectoryTree).reload()
+
+    def action_toggle_env(self) -> None:
+        """F3: switch between the server and local environments (only when logged in)."""
+        if not store.get_key():
+            return                       # no toggle when not authenticated
+        self._env = "local" if self._env == "server" else "server"
+        self._apply_env()
+        if self._env == "server":
+            self._start_loaders()
+
+    def check_action(self, action: str, parameters):
+        """Hide the environment toggle from the footer when not logged in."""
+        if action == "toggle_env":
+            return True if store.get_key() else None   # None -> hidden + disabled
+        return True
+
+    def _apply_env(self) -> None:
+        """Show the tree for the current environment; update the panel title + status."""
+        server = self._env == "server"
+        self.query_one("#resources", Tree).display = server
+        self.query_one("#workspace-tree", DirectoryTree).display = not server
+        self.query_one("#workspace-input", Input).display = not server
+        self.query_one("#resources-panel", Vertical).border_title = (
+            "Resources" if server else "Workspace"
+        )
+        self._update_env_status()
+
+    def _set_workspace(self, path: str) -> None:
+        """Validate + persist a new workspace path, then reload the local tree."""
+        try:
+            resolved = config.resolve_workspace(path)
+        except ValueError as exc:
+            self._set_status(f"⚠ {exc}")
+            return
+        self._workspace = resolved
+        self.config["workspace"] = resolved
+        config.save(self.config)
+        self.query_one("#workspace-input", Input).value = resolved
+        self.query_one("#workspace-tree", DirectoryTree).path = resolved   # reactive -> reloads
+        self._update_env_status()        # refresh "local · <path>"
+
+    def _update_env_status(self) -> None:
+        """Set the bottom status line based on auth state and current environment."""
+        if not store.get_key():
+            self._set_status("○ Not authenticated · sagex auth login")
+        elif self._env == "local":
+            self._set_status(f"local · {self._workspace}")
+        else:
+            self._set_status("")         # server ok; a load error will overwrite this
+
+    def _set_status(self, text: str) -> None:
+        """Set the one-line status bar under the resources tree."""
+        self.query_one("#resources-status", Static).update(text)
+
+    @work(thread=True)
+    def _load_branch(self, node, fetch, gen: int) -> None:
+        """Fetch display labels for a tree branch in a background thread.
+
+        `fetch` takes an ApiClient and returns a list of labels (str or Text).
+        """
+        try:
+            labels = fetch(build_client())
+        except ApiError as exc:
+            self.call_from_thread(self._fill_branch, node, None, exc.message, gen)
+            return
+        self.call_from_thread(self._fill_branch, node, labels, None, gen)
+
+    def _fill_branch(self, node, labels, error, gen: int) -> None:
+        """(main thread) Fill a branch with results; route any error to one status line."""
+        if gen == self._load_gen:        # a stale load (before an F5) doesn't count
+            self._pending_loads.discard(id(node))
+            if not self._pending_loads:
+                self.query_one("#resources-activity", ActivityLine).stop()
+        node.remove_children()           # clear the "Loading…" placeholder
+        if error:
+            self._set_status(f"⚠ {error}  ·  F5 to retry")   # one shared message, not per-branch
+            return
+        if not labels:
+            node.add_leaf("(none)")
+        else:
+            for label in labels:
+                node.add_leaf(label)   # names already trimmed at construction (metadata kept)

sagex/app.tcss

@@ -0,0 +1,63 @@
+/* sagex styling (Textual CSS). Loaded by SagexApp via CSS_PATH = "app.tcss". */
+
+Horizontal {
+    height: 1fr;                 /* fill space between header and footer */
+}
+
+/* One uniform background: make the header, footer, AND the tree all
+   transparent so the single screen background shows through everywhere. */
+Header, Footer, Tree {
+    background: transparent;
+}
+
+#resources-panel {
+    width: 30%;                  /* left panel takes 30% of the width */
+    border: round $primary;
+}
+#resources {
+    height: 1fr;                 /* tree fills the panel above the status bar */
+}
+#workspace-input {
+    height: auto;               /* the local-env path box (shown only in local) */
+}
+#workspace-tree {
+    height: 1fr;                 /* local file tree fills the same space */
+}
+#resources-status {
+    height: auto;               /* 0 rows when empty, one line when it has text */
+    color: $text-muted;
+    padding: 0 1;
+}
+
+/* Right: the terminal-style transcript — entries flow down to the prompt line. */
+#chat-log {
+    width: 70%;                  /* the remaining 70% */
+    height: 1fr;
+    padding: 0 1;
+}
+#welcome {
+    width: auto;                 /* hug the banner text */
+    border: round #d77757;
+    padding: 0 1;
+}
+#command-activity {
+    margin-top: 1;
+}
+#prompt-row {
+    height: auto;
+    margin-top: 1;               /* a blank line above the prompt, like a fresh turn */
+}
+#prompt-glyph {
+    width: 2;
+    color: #d77757;              /* the same accent as the ❯ on past entries */
+    text-style: bold;
+}
+#chat-input, #chat-input:focus {
+    width: 1fr;
+    background: transparent;     /* no box: you type straight onto the line */
+    background-tint: transparent;
+}
+#prompt-status {
+    height: auto;
+    color: $text-muted;
+}

sagex/config.py

@@ -0,0 +1,88 @@
+"""Persistent user settings, stored at ~/.sagex/config.json.
+
+A tiny load/save layer over a JSON file. Deliberately fail-soft: a missing or
+corrupt file falls back to defaults, and a failed write never crashes the app —
+losing a preference is not worth interrupting the user.
+"""
+
+import json
+import os
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".sagex"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+try:
+    from sagex._env import VALUES as _BAKED    # written from .env at build time (setup.py)
+except ImportError:                            # a checkout that was never built/installed
+    _BAKED = {}
+
+
+def _baked(name: str) -> str:
+    value = _BAKED.get(name)
+    if not value:
+        raise RuntimeError(
+            f"{name} isn't configured. In the sagex checkout: cp .env.example .env, "
+            "fill it in, then run: pip install -e ."
+        )
+    return value.rstrip("/")
+
+
+# The hosted Autosage API. Override per-shell with SAGEX_API_URL (see api_url()), or
+# persistently with "api_url" in config.json — e.g. a local dev stack on :8080.
+DEFAULT_API_URL = _baked("SAGEX_API_URL")
+
+# The Autosage web app — where users request a key and (until sagex v2) chat with Autobot.
+WEB_URL = _baked("SAGEX_WEB_URL")
+
+# Every setting the app understands, with its default value.
+DEFAULTS = {
+    "shell": None,                        # None = auto-detect the default shell
+    "api_url": DEFAULT_API_URL,
+}
+
+
+def load() -> dict:
+    """Return settings (file values merged over defaults). Never raises."""
+    settings = dict(DEFAULTS)
+    try:
+        with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+            settings.update(json.load(f))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        pass                          # missing/broken file -> just use defaults
+    return settings
+
+
+def save(settings: dict) -> None:
+    """Write settings to disk, creating ~/.sagex if needed. Best-effort."""
+    try:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+            json.dump(settings, f, indent=2)
+    except OSError:
+        pass                          # can't write? oh well — don't crash
+
+
+def api_url() -> str:
+    """The backend base URL: SAGEX_API_URL, else config.json, else the hosted API.
+
+    The env override is read here rather than merged in load(), so a later save()
+    (e.g. the TUI remembering your shell) never writes it into config.json.
+    """
+    return os.environ.get("SAGEX_API_URL", "").strip() or load()["api_url"]
+
+
+def resolve_workspace(path: str) -> str:
+    """Expand + resolve a workspace path to an absolute one, or raise ValueError.
+
+    Relative paths resolve against the current directory. Env vars and ~ expand.
+    """
+    resolved = os.path.abspath(os.path.expanduser(os.path.expandvars((path or "").strip())))
+    if not os.path.isdir(resolved):
+        raise ValueError(f"Not a folder: {resolved}")
+    return resolved
+
+
+def workspace_dir() -> str:
+    """The effective workspace folder: the saved one, else the current directory."""
+    return load().get("workspace") or os.getcwd()