scriptit-cli 0.2.2__py3-none-any.whl

scriptit_cli/commands.py

@@ -0,0 +1,302 @@
+"""Workstation-side commands for remote sandbox access.
+
+``fs`` wraps the platform's file API; ``session`` manages the sticky anchor
+session that remote shell commands run in; ``context`` fetches the complete
+agent context; ``sandbox`` surfaces lifecycle state. These are client
+conveniences — every other verb passes through and runs inside the sandbox.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any, Dict, Optional
+
+from scriptit_cli import MIN_SANDBOX_CLI_VERSION
+from scriptit_cli.analytics import analytics
+from scriptit_cli.client import detect_client
+from scriptit_cli.errors import ScriptItError
+from scriptit_cli.output import emit, fail
+from scriptit_cli.remote import ENV_SESSION, RemoteClient, update_state
+
+
+def _session_urls(client: RemoteClient, session_id: Optional[str]) -> Dict[str, Optional[str]]:
+    session_url = f"{client.app_url}/app/s/{session_id}" if client.app_url and session_id else None
+    return {"session_url": session_url}
+
+
+def _fetch_context_bundle(
+    client: RemoteClient,
+    sandbox_id: str,
+    session_id: str,
+) -> Dict[str, Any]:
+    # The sandbox assembles the briefing from its own state (integrations,
+    # skills, its CLI version, mounted workspaces); this side contributes
+    # only what the sandbox cannot know — which session, the app origin the
+    # client logged into, and the client's compatibility floor.
+    context_data: Dict[str, Any] = {
+        "session_id": session_id,
+        **_session_urls(client, session_id),
+        "minimum_sandbox_version": MIN_SANDBOX_CLI_VERSION,
+    }
+    return client.agent_context(sandbox_id, context_data)
+
+
+def _client_or_exit() -> RemoteClient:
+    try:
+        return RemoteClient()
+    except ScriptItError as exc:
+        fail(str(exc))
+
+
+def _run(fn, *args: Any, **kwargs: Any) -> Any:
+    # OSError covers local-file failures (push of a missing file, pull into
+    # an unwritable path) — formatted like transport errors, no traceback.
+    try:
+        return fn(*args, **kwargs)
+    except (ScriptItError, OSError) as exc:
+        fail(str(exc))
+
+
+def show_context() -> None:
+    """Fetch and print the complete external-agent context for this session."""
+    client = _client_or_exit()
+    sandbox_id = _run(client.ensure_sandbox)
+    session_id, _, _ = client.anchor()
+    if not session_id:
+        fail("no current session; run `scriptit session new` first")
+    if not _run(client.session_exists, sandbox_id, session_id):
+        fail(f"session {session_id} not found in sandbox {sandbox_id}")
+    attributed_client = _run(client.ensure_session_attribution, sandbox_id, session_id)
+    if attributed_client:
+        update_state(client.state_key, client=attributed_client)
+    bundle = _run(_fetch_context_bundle, client, sandbox_id, session_id)
+    emit(bundle, lambda: print(bundle["markdown"]))
+
+
+class FsCommands:
+    """Files in your sandbox. A relative path starts where `exec` runs, the
+    current session's directory (workspaces/<wid>/..., data_files/...)."""
+
+    def read(self, path: str) -> None:
+        """Print a sandbox file to stdout (bytes pass through unmodified)."""
+        client = _client_or_exit()
+        sandbox_id = _run(client.ensure_sandbox)
+        path = _run(client.resolve_fs_path, sandbox_id, path)
+        data: bytes = _run(client.fs_read, sandbox_id, path)
+        sys.stdout.buffer.write(data)
+        sys.stdout.buffer.flush()
+
+    def write(self, path: str, content: str) -> None:
+        """Write text content to a sandbox file (creates parent dirs)."""
+        client = _client_or_exit()
+        sandbox_id = _run(client.ensure_sandbox)
+        path = _run(client.resolve_fs_path, sandbox_id, path)
+        _run(client.fs_write, sandbox_id, path, content)
+        emit(
+            {"path": path, "bytes": len(content.encode("utf-8"))},
+            lambda: print(f"Wrote {path}"),
+        )
+
+    def push(self, local: str, remote: str) -> None:
+        """Upload a local file into the sandbox (binary-safe, ≤30MB)."""
+        client = _client_or_exit()
+        sandbox_id = _run(client.ensure_sandbox)
+        remote = _run(client.resolve_fs_path, sandbox_id, remote)
+        _run(client.fs_upload, sandbox_id, remote, local)
+        emit(
+            {"local": local, "remote": remote},
+            lambda: print(f"Pushed {local} -> {remote}"),
+        )
+
+    def pull(self, remote: str, local: str) -> None:
+        """Download a sandbox file to a local path (parents auto-created).
+
+        A directory destination gets the remote basename appended, so
+        ``scriptit fs pull /remote/report.txt .`` lands ``./report.txt``.
+        """
+        client = _client_or_exit()
+        sandbox_id = _run(client.ensure_sandbox)
+        remote = _run(client.resolve_fs_path, sandbox_id, remote)
+        data: bytes = _run(client.fs_read, sandbox_id, remote)
+        # A trailing slash names a directory even before it exists.
+        if os.path.isdir(local) or local.endswith(("/", os.sep)):
+            local = os.path.join(local, os.path.basename(remote.rstrip("/")))
+
+        def _write_local() -> None:
+            parent = os.path.dirname(local)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+            with open(local, "wb") as f:
+                f.write(data)
+
+        # An unwritable or invalid destination is an ordinary error, not a
+        # traceback — the same treatment the remote half already gets.
+        _run(_write_local)
+        emit(
+            {"remote": remote, "local": local, "bytes": len(data)},
+            lambda: print(f"Pulled {remote} -> {local} ({len(data)} bytes)"),
+        )
+
+
+_ANCHOR_SOURCES = {
+    "env": f"{ENV_SESSION} environment variable",
+    "state": "sticky anchor for this login",
+    "none": "none yet",
+}
+
+
+class SessionCommands:
+    """The anchor session remote commands run in (visible in the app UI)."""
+
+    def new(self) -> None:
+        """Create a fresh anchor session and make it current."""
+        client = _client_or_exit()
+        sandbox_id = _run(client.ensure_sandbox)
+        session_id = _run(client.create_session, sandbox_id)
+        update_state(
+            client.state_key,
+            sandbox_id=sandbox_id,
+            session_id=session_id,
+            client=detect_client(),
+        )
+        # The funnel's first real step: a harness that gets this far has a
+        # working credential and a live sandbox to drive.
+        analytics.track("cli_session_created")
+
+        def _human() -> None:
+            print(f"Anchor session: {session_id} (sandbox {sandbox_id})")
+
+        payload: Dict[str, Any] = {
+            "session_id": session_id,
+            "sandbox_id": sandbox_id,
+        }
+        emit(payload, _human)
+
+    def current(self) -> None:
+        """Show the current anchor session, where it came from, and its app URL."""
+        client = _client_or_exit()
+        session_id, sandbox_id, source = client.anchor()
+        # Carried here as well as in `context`: this is the command an agent
+        # runs when it already has a session and just needs to know which, and
+        # a link it cannot get here is a link it will try to build itself.
+        link = _session_urls(client, session_id)
+
+        def _human() -> None:
+            if not session_id:
+                print("No anchor session yet — one is created on first use.")
+                return
+            print(f"session: {session_id}")
+            print(f"sandbox: {sandbox_id}")
+            print(f"source:  {_ANCHOR_SOURCES[source]}")
+            if link["session_url"]:
+                print(f"app:     {link['session_url']}")
+
+        emit(
+            {
+                "session_id": session_id,
+                "sandbox_id": sandbox_id,
+                "anchor_source": source,
+                **link,
+            },
+            _human,
+        )
+
+    def use(self, session_id: str) -> None:
+        """Point remote commands at an existing session id."""
+        client = _client_or_exit()
+        sandbox_id = _run(client.ensure_sandbox)
+        if not _run(client.session_exists, sandbox_id, session_id):
+            fail(f"session {session_id} not found in sandbox {sandbox_id}")
+        attributed_client = _run(client.ensure_session_attribution, sandbox_id, session_id)
+        update_state(
+            client.state_key,
+            sandbox_id=sandbox_id,
+            session_id=session_id,
+            client=attributed_client,
+        )
+
+        def _human() -> None:
+            print(f"Anchor session set to {session_id}")
+
+        payload: Dict[str, Any] = {
+            "session_id": session_id,
+            "sandbox_id": sandbox_id,
+        }
+        emit(payload, _human)
+
+    def list(self, page_size: int = 20) -> None:
+        """List recent sessions in the sandbox."""
+        client = _client_or_exit()
+        sandbox_id = _run(client.ensure_sandbox)
+        resp = _run(
+            client.request,
+            "GET",
+            f"/api/v1/sandbox/{sandbox_id}/proxy/sessions/list",
+            params={"pageSize": page_size},
+            timeout=60,
+        )
+        if resp.status_code != 200:
+            fail(f"sessions list failed ({resp.status_code})")
+        sessions = resp.json().get("sessions") or []
+        current, _, _ = client.anchor()
+
+        def _human() -> None:
+            for entry in sessions:
+                sid = entry.get("id") or entry.get("sessionId")
+                title = (entry.get("title") or "").strip() or "(untitled)"
+                print(f"{sid}  {title}{' *' if sid == current else ''}")
+
+        emit({"current": current, "sessions": sessions}, _human)
+
+
+class SandboxCommands:
+    """Sandbox lifecycle, as seen from outside."""
+
+    def status(self) -> None:
+        """Show your sandboxes and their states."""
+        client = _client_or_exit()
+        sandboxes = _run(client.list_sandboxes)
+        rows = []
+        for sb in sandboxes:
+            sid = sb.get("sandbox_id")
+            resp = _run(
+                client.request,
+                "GET",
+                f"/api/v1/sandbox/{sid}/status",
+                wake_on_503=False,
+                timeout=30,
+            )
+            rows.append(
+                {
+                    "sandbox_id": sid,
+                    "state": resp.json().get("state", "unknown")
+                    if resp.status_code == 200
+                    else "unknown",
+                    "is_active": bool(sb.get("is_active")),
+                    "workspaces": [
+                        w.get("name") or w.get("workspace_id", "?")
+                        for w in (sb.get("accessible_workspaces") or [])
+                    ],
+                }
+            )
+
+        def _human() -> None:
+            if not rows:
+                print("No sandbox yet — one is created on first use.")
+                return
+            for row in rows:
+                active = " (active)" if row["is_active"] else ""
+                names = ", ".join(row["workspaces"]) or "-"
+                print(f"{row['sandbox_id']}  {row['state']}{active}  workspaces: {names}")
+
+        emit({"sandboxes": rows}, _human)
+
+    def wake(self) -> None:
+        """Wake the active sandbox (resume if paused) and wait until ready."""
+        client = _client_or_exit()
+        sandbox_id = _run(client.ensure_sandbox)
+        emit(
+            {"sandbox_id": sandbox_id, "state": "ready"},
+            lambda: print(f"Sandbox {sandbox_id} is ready."),
+        )

scriptit_cli/config.py

@@ -0,0 +1,19 @@
+"""Where the client keeps its state.
+
+Credentials and the per-profile anchor-session state live in one directory, so
+a machine is disconnected by removing it.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def _config_dir() -> str:
+    """``$XDG_CONFIG_HOME/scriptit``, else ``~/.config/scriptit``.
+
+    The same directory the in-sandbox CLI uses, so a machine that has both
+    installed shares one set of credentials.
+    """
+    xdg = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
+    return os.path.join(xdg, "scriptit")

scriptit_cli/errors.py

@@ -0,0 +1,21 @@
+"""The exception hierarchy.
+
+Every failure the user should see as one line rather than a traceback derives
+from :class:`ScriptItError`. Handlers catch the base, so a new error type is
+covered everywhere the day it is added — the previous per-type tuples meant
+each new call site had to remember the full list, and one eventually would not.
+"""
+
+from __future__ import annotations
+
+
+class ScriptItError(RuntimeError):
+    """Anything the CLI should report as a message, not a stack trace."""
+
+
+class RemoteAuthError(ScriptItError):
+    """Credential problems: not logged in, refresh failed, store unusable."""
+
+
+class RemoteError(ScriptItError):
+    """Transport-level failures talking to Script.it."""

scriptit_cli/main.py

@@ -0,0 +1,184 @@
+"""``scriptit`` entry point.
+
+Routing is by verb: ``exec`` and everything this client does not answer itself
+go to the sandbox; :data:`~scriptit_cli.remote.CLIENT_COMMANDS` are handled
+here. Nothing in this package imports or executes the Script.it runtime — the
+sandbox's own CLI is what runs automation.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import sys
+import time
+from typing import List, Tuple
+
+import fire
+
+from scriptit_cli import __version__, output, update_check
+from scriptit_cli.analytics import analytics, safe_command
+from scriptit_cli.auth import AuthCommands
+from scriptit_cli.commands import FsCommands, SandboxCommands, SessionCommands, show_context
+from scriptit_cli.output import emit, set_json_mode, warn
+from scriptit_cli.remote import CLIENT_COMMANDS, remote_dispatch_if_applicable, remote_exec
+
+JSON_FLAG = "--json"
+
+
+# Commands whose output this client formats, so `--json` is ours to read.
+# `exec` is absent on purpose: everything after it is the user's command, and
+# consuming a `--json` out of it would change what runs.
+JSON_COMMANDS = frozenset({"auth", "context", "fs", "session", "sandbox", "version"})
+
+# ...minus the ones inside those groups that stream raw bytes instead of
+# returning a result. `fs read` writes the file unmodified, which is the point
+# of it — so rather than promise one JSON document and then not produce one,
+# `--json` is a no-op there and the flag is simply consumed.
+JSON_STREAMING_COMMANDS = frozenset({("fs", "read")})
+
+
+def extract_json_flag(argv: List[str]) -> Tuple[List[str], bool]:
+    """Pull ``--json`` out of a client invocation, without touching data.
+
+    Two things are never ours to consume: a forwarded verb's flags, which
+    belong to the sandbox's CLI, and anything after ``--``, which is opaque
+    payload — `scriptit exec -- tool --json` must run `tool --json`.
+
+    A positional value that happens to spell ``--json`` is indistinguishable
+    from the flag at this layer (as it is to any flag parser); pass such a
+    value as ``--content=--json`` instead.
+    """
+    if not argv or argv[0] not in JSON_COMMANDS:
+        return argv, False
+    cut = argv.index("--") if "--" in argv else len(argv)
+    head, tail = argv[:cut], argv[cut:]
+    if JSON_FLAG not in head:
+        return argv, False
+    stripped = [a for a in head if a != JSON_FLAG] + tail
+    streaming = tuple(stripped[:2]) in JSON_STREAMING_COMMANDS
+    return stripped, not streaming
+
+
+class ScriptIt:
+    """Drive your Script.it sandbox from this machine.
+
+    Connect:
+        scriptit auth login                    # browser sign-in, stores a token
+        scriptit auth status                   # who am I, which deployment
+
+    Work in the sandbox:
+        scriptit exec -- <command>             # arbitrary shell
+        scriptit exec --timeout 60 -- <cmd>    # ...bounded sandbox-side
+        scriptit start <script>                # ...and every other verb, which
+        scriptit trigger list                  #    the sandbox's CLI answers
+        scriptit describe --concepts           # the platform reference
+
+    Move files and manage the session:
+        scriptit fs read|write|push|pull
+        scriptit context                     # fetch agent instructions
+        scriptit session new|use|current|list
+        scriptit sandbox status|wake
+
+    Add --json to any of this client's own commands for machine-readable
+    output: stdout becomes one JSON document, everything else goes to stderr.
+
+    Everything runs in a session that is visible in the Script.it app.
+    """
+
+    def __init__(self) -> None:
+        self.auth = AuthCommands()
+        self.fs = FsCommands()
+        self.session = SessionCommands()
+        self.sandbox = SandboxCommands()
+
+    def context(self) -> None:
+        """Fetch the complete agent context for the current session."""
+        show_context()
+
+    def version(self) -> None:
+        """Print this client's version."""
+        emit(
+            {"version": __version__},
+            lambda: print(f"scriptit-cli {__version__}"),
+        )
+
+
+def _route(argv: List[str]) -> int:
+    """Run one invocation and return its exit status."""
+    if argv and argv[0] in ("--version", "-V"):
+        print(f"scriptit-cli {__version__}")
+        return 0
+
+    if argv and argv[0] == "exec":
+        return remote_exec(argv[1:])
+
+    handled = remote_dispatch_if_applicable(argv)
+    if handled is not None:
+        return handled
+
+    # Fire parses sys.argv directly, so the --json it must not see is removed.
+    sys.argv = [sys.argv[0], *argv]
+    fire.Fire(ScriptIt, name="scriptit")
+    return 0
+
+
+def _ensure_json_error(code: int) -> None:
+    """Keep the ``--json`` contract on a failure that never reached `output`.
+
+    `fail()` writes ``{"error": ...}`` for everything this client rejects
+    itself, but Fire answers a bad command line by printing usage and exiting
+    on its own. Without this, `scriptit session use --json` exits 2 with an
+    empty stdout — a caller parsing stdout gets nothing to parse, which is
+    exactly what the contract exists to prevent. Fire's own message is already
+    on stderr, where a non-result belongs.
+    """
+    if not output.json_mode() or output.emitted():
+        return
+    json.dump(
+        {"error": f"command failed (exit {code}); see stderr for details"},
+        sys.stdout,
+        indent=2,
+    )
+    sys.stdout.write("\n")
+
+
+def main() -> None:
+    argv, json_mode = extract_json_flag(sys.argv[1:])
+    set_json_mode(json_mode)
+
+    notice = update_check.check()
+    if notice:
+        warn(notice)
+
+    started = time.monotonic()
+    code = 0
+    try:
+        code = _route(argv)
+        if code != 0:
+            _ensure_json_error(code)
+    except SystemExit as exc:
+        # Fire exits directly on `--help` and on a usage error; that status is
+        # the invocation's outcome and belongs in the event like any other.
+        code = exc.code if isinstance(exc.code, int) else (0 if exc.code is None else 1)
+        if code != 0:
+            _ensure_json_error(code)
+        raise
+    finally:
+        # Wrapped: a broken analytics path must not turn a successful command
+        # into a traceback, or change the status the caller sees.
+        with contextlib.suppress(Exception):
+            analytics.track(
+                "cli_command_completed",
+                command=safe_command(argv),
+                forwarded=bool(argv) and argv[0] not in CLIENT_COMMANDS,
+                exit_code=code,
+                ok=code == 0,
+                duration_ms=int((time.monotonic() - started) * 1000),
+                json_mode=json_mode,
+            )
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

scriptit_cli/output.py

@@ -0,0 +1,79 @@
+"""Human vs machine output.
+
+``--json`` makes stdout exactly one JSON document and sends everything else —
+progress, warnings, errors — to stderr. That contract is what lets a caller
+pipe stdout straight into a parser without stripping chatter first, which
+matters here because the usual caller is an agent.
+
+Human mode is unchanged: prose on stdout, errors on stderr.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Callable, NoReturn
+
+_json_mode = False
+_emitted = False
+
+
+def set_json_mode(enabled: bool) -> None:
+    global _json_mode
+    _json_mode = enabled
+
+
+def json_mode() -> bool:
+    return _json_mode
+
+
+def emitted() -> bool:
+    """Whether the one JSON document has already been written.
+
+    The entry point uses this to answer a failure that never reached this
+    module — an argument parser rejecting the command line, say — without
+    writing a second document over a real result.
+    """
+    return _emitted
+
+
+def emit(payload: Any, human: Callable[[], None]) -> None:
+    """The command's result: one JSON document, or whatever ``human`` prints."""
+    global _emitted
+    if _json_mode:
+        json.dump(payload, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+        _emitted = True
+    else:
+        human()
+
+
+def note(message: str) -> None:
+    """Progress and advisories — never part of the result.
+
+    Flushed: callers print a URL and then block waiting for the browser, and
+    through a pipe an unflushed line would not appear until the wait ended.
+    """
+    print(message, file=sys.stderr if _json_mode else sys.stdout, flush=True)
+
+
+def warn(message: str) -> None:
+    """Always stderr: a warning is not a result in either mode."""
+    print(message, file=sys.stderr, flush=True)
+
+
+def fail(message: str, code: int = 1) -> NoReturn:
+    """Report an error and exit.
+
+    In JSON mode this is still the one document on stdout — a caller that
+    parses stdout gets a structured reason instead of an empty stream plus
+    prose it would have to read.
+    """
+    global _emitted
+    if _json_mode:
+        json.dump({"error": message}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+        _emitted = True
+    else:
+        print(f"Error: {message}", file=sys.stderr)
+    sys.exit(code)