stcode 0.0.1a0__py3-none-any.whl

stcode/cli/logic/completion.py

@@ -0,0 +1,43 @@
+"""Token completion independent of terminal widgets."""
+
+from __future__ import annotations
+from typing import Sequence
+from stcode.cli.models import Row
+
+TRIGGERS = ("/", "@")
+
+
+def token_trigger(text: str, cursor: int) -> tuple[str, str] | None:
+    """The `/` or `@` token the cursor is inside, as `(symbol, filter)`.
+
+    A token starts at the beginning of the line or after whitespace, which is the whole
+    rule: `src/api` is a path and `me@example.com` is an address, and neither should
+    hijack the input. It ends at whitespace, so `/mode plan` is past the command.
+    """
+    if cursor <= 0 or cursor > len(text):
+        return None
+    start = cursor
+    while start > 0 and not text[start - 1].isspace():
+        start -= 1
+    token = text[start:cursor]
+    if not token or token[0] not in TRIGGERS:
+        return None
+    return token[0], token[1:]
+
+
+def filter_rows(rows: Sequence[Row], query: str) -> list[Row]:
+    """Narrow on a substring of the **label**, case-insensitively.
+
+    The label only, and that is the interesting part. Searching the descriptions too
+    looks generous and reads as noise: typing `/mod` would offer `/effort`, whose
+    description happens to say "how hard the model should think". What you are typing
+    is a name, so a name is what it matches — and `?` already lists all twelve with
+    their descriptions for the times you do not know the name.
+
+    Substring, not fuzzy. The fuzzy command palette was removed on purpose: two ways to
+    reach the same twelve commands is one way for them to disagree.
+    """
+    if not query:
+        return list(rows)
+    needle = query.lower()
+    return [row for row in rows if needle in row[0].lower()]

stcode/cli/logic/connection.py

@@ -0,0 +1,46 @@
+"""Connection ownership and cleanup; interaction with the user stays in the UI."""
+
+from __future__ import annotations
+
+import contextlib
+
+from stcode.cli.services.client import Address, DaemonClient
+from stcode.cli.services.launcher import Launcher
+
+
+class Connection:
+    def __init__(self, launcher: Launcher) -> None:
+        self.launcher = launcher
+        self.client: DaemonClient | None = None
+
+    @property
+    def address(self) -> Address:
+        return self.launcher.address
+
+    @property
+    def started(self) -> bool:
+        return self.launcher.started
+
+    async def close_client(self) -> None:
+        client, self.client = self.client, None
+        if client is not None:
+            with contextlib.suppress(Exception):
+                await client.aclose()
+
+    async def open(
+        self, *, address: Address | None = None, restart: bool = False
+    ) -> DaemonClient:
+        await self.close_client()
+        if address is None:
+            client = await self.launcher.connect(restart=restart)
+        else:
+            client = await DaemonClient.connect(address)
+            self.launcher.address = address
+        self.client = client
+        return client
+
+    async def aclose(self) -> None:
+        try:
+            await self.close_client()
+        finally:
+            await self.launcher.stop()

stcode/cli/logic/requests.py

@@ -0,0 +1,18 @@
+"""FIFO requests keep parallel approvals and questions individually answerable."""
+
+from collections import deque
+from typing import Any
+
+
+class RequestQueue:
+    def __init__(self) -> None:
+        self._pending: deque[dict[str, Any]] = deque()
+
+    def append(self, frame: dict[str, Any]) -> None:
+        self._pending.append(frame)
+
+    def pop(self) -> dict[str, Any] | None:
+        return self._pending.popleft() if self._pending else None
+
+    def clear(self) -> None:
+        self._pending.clear()

stcode/cli/logic/sessions.py

@@ -0,0 +1,67 @@
+"""Session operations preserve the distinction between local and daemon workspaces."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from stcode.cli.models import StartOptions
+from stcode.cli.services.client import DaemonClient
+from .connection import Connection
+from .state import ClientState
+
+
+class Sessions:
+    def __init__(
+        self, connection: Connection, state: ClientState, options: StartOptions
+    ) -> None:
+        self.connection = connection
+        self.state = state
+        self.options = options
+
+    @property
+    def client(self) -> DaemonClient:
+        client = self.connection.client
+        if client is None:
+            raise ConnectionError("No daemon is connected")
+        return client
+
+    async def open(self) -> dict[str, Any]:
+        if self.options.resume:
+            return await self.client.attach(self.options.resume)
+        cwd = (
+            self.options.cwd
+            if self.options.explicit_cwd or not self.options.daemonless
+            else None
+        )
+        return await self.client.create(
+            cwd=cwd, role=self.options.role, approval_mode=self.options.mode
+        )
+
+    async def list(self) -> list[dict[str, Any]]:
+        return await self.client.sessions(50)
+
+    async def detach(self) -> None:
+        await self.client.detach(self.state.session_id)
+
+    async def attach(self, session_id: str) -> dict[str, Any]:
+        return await self.client.attach(session_id)
+
+    async def clear(self) -> dict[str, Any]:
+        previous = self.state.session_id
+        frame = await self.client.create(
+            cwd=self.options.cwd,
+            role=self.options.role,
+            approval_mode=self.options.mode,
+        )
+        if previous:
+            await self.client.detach(previous)
+        return frame
+
+    async def load_info(self) -> None:
+        self.state.info = await self.client.info()
+
+    async def push(self, text: str) -> None:
+        await self.client.push(text)
+
+    async def interrupt(self) -> None:
+        await self.client.interrupt()

stcode/cli/logic/settings.py

@@ -0,0 +1,35 @@
+"""Write defaults before session overrides; the daemon is authoritative."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from stcode.cli.models import ApprovalMode
+from stcode.cli.services.client import DaemonClient
+from .state import ClientState
+
+
+class Settings:
+    def __init__(self, state: ClientState) -> None:
+        self.state = state
+
+    async def set_config(self, client: DaemonClient, **fields: Any) -> None:
+        self.state.config = await client.set_config(**fields)
+
+    async def apply(self, client: DaemonClient, patch: dict[str, Any]) -> None:
+        await self.set_config(client, **patch)
+        if self.state.session_id:
+            await client.set_meta(
+                provider=str(self.state.config.get("provider", "")),
+                model=str(self.state.config.get("model", "")),
+            )
+
+    async def set_mode(self, client: DaemonClient, mode: ApprovalMode) -> None:
+        await self.set_config(client, approval_mode=mode)
+        if self.state.session_id:
+            await client.set_mode(mode)
+
+    async def set_effort(self, client: DaemonClient, effort: str) -> None:
+        await self.set_config(client, reasoning_effort=effort)
+        if self.state.session_id:
+            await client.set_meta(reasoning_effort=effort)

stcode/cli/logic/state.py

@@ -0,0 +1,43 @@
+"""The last facts reported by the daemon, independent of terminal widgets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ClientState:
+    session_id: str = ""
+    config: dict[str, Any] = field(default_factory=dict)
+    effective: dict[str, str] = field(default_factory=dict)
+    info: dict[str, Any] = field(default_factory=dict)
+
+    def adopt_session(self, frame: dict[str, Any]) -> None:
+        session_id = str(frame.get("id", ""))
+        if session_id:
+            self.session_id = session_id
+        self.effective = {
+            "model": str(frame.get("model", "")),
+            "provider": str(frame.get("provider", "")),
+            "effort": str(frame.get("reasoning_effort", "")),
+            "mode": str(frame.get("approval_mode", "")),
+        }
+
+    @property
+    def provider(self) -> str:
+        return self.effective.get("provider") or str(self.config.get("provider", ""))
+
+    @property
+    def provider_entry(self) -> dict[str, Any]:
+        return dict(self.config.get("providers", {}).get(self.provider, {}))
+
+    @property
+    def effort(self) -> str:
+        return self.effective.get("effort") or str(
+            self.config.get("reasoning_effort", "")
+        )
+
+    @property
+    def has_credential(self) -> bool:
+        return bool(self.provider_entry.get("has_key"))

stcode/cli/logic/workspace.py

@@ -0,0 +1,17 @@
+"""Workspace requests always target the attached daemon session."""
+
+from typing import Any
+
+from stcode.cli.models import UiPrefs
+from stcode.cli.services.client import DaemonClient
+
+
+class Workspace:
+    def __init__(self, prefs: UiPrefs) -> None:
+        self.prefs = prefs
+
+    async def files(self, client: DaemonClient) -> list[str]:
+        return await client.workspace_files()
+
+    async def shell(self, client: DaemonClient, command: str) -> dict[str, Any]:
+        return await client.workspace_shell(command, self.prefs.shell_timeout)

stcode/cli/main.py

@@ -0,0 +1,290 @@
+"""
+CLI entrypoint — one command, three shapes.
+
+    stcode                 chat UI + a daemon (started here if none is listening)
+    stcode --headless      the daemon alone — a container's whole process
+    stcode --daemonless    the chat UI alone, pointed at a daemon somewhere else
+
+The daemon is its own program, `stcode-daemon`. `--headless` replaces this process with
+it; the UI starts it in the background when nothing listens, and stops it on exit.
+`--restart` stops a running local daemon first, for when it is wedged or its code
+changed.
+
+`stcode <path>` opens a session in that directory. It is a rewrite to `--cwd` rather
+than an argument on the group, because a `click` group consumes its own arguments before
+it looks for a subcommand — declaring one there makes `stcode sessions` mean "open the
+directory ./sessions". Only the **first** token is read this way, and only when it is
+not a subcommand, so the grammar stays "the path comes first, flags after".
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+from typing import Annotated, Any, Awaitable, Callable, NoReturn
+
+import typer
+
+from stcode import __version__
+from stcode.cli.services.client import Address, DaemonClient
+from stcode.cli.models import APPROVAL_MODES, ApprovalMode
+from stcode.cli.logic.commands import parse_approval_mode
+from stcode.cli.services.launcher import DaemonFailed, Launcher, daemon_command
+
+cli = typer.Typer(
+    name="stcode",
+    help="stcode — a coding agent for the terminal: a daemon holding the agent, and a UI attached to it.",
+    no_args_is_help=False,
+    add_completion=False,
+)
+
+ConfigOption = Annotated[
+    Path | None,
+    typer.Option(
+        "--config", "-c", help="Config file to use instead of the default location."
+    ),
+]
+
+
+@cli.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    config: ConfigOption = None,
+    headless: Annotated[
+        bool,
+        typer.Option(
+            "--headless", help="Run the daemon only, with no UI. What a container runs."
+        ),
+    ] = False,
+    daemonless: Annotated[
+        bool,
+        typer.Option(
+            "--daemonless",
+            help="Run the UI only, attached to a daemon elsewhere. Asks for the address if none answers.",
+        ),
+    ] = False,
+    restart: Annotated[
+        bool,
+        typer.Option(
+            "--restart", help="Stop the local daemon first and start a fresh one."
+        ),
+    ] = False,
+    cwd: Annotated[
+        Path | None,
+        typer.Option(
+            "--cwd",
+            "-C",
+            help="Workspace for the session. Defaults to the current directory. "
+            "`stcode <path>` is the same thing, spelled shorter.",
+        ),
+    ] = None,
+    mode: Annotated[
+        str | None,
+        typer.Option(
+            "--mode", "-m", help=f"Approval mode: {' | '.join(APPROVAL_MODES)}."
+        ),
+    ] = None,
+    resume: Annotated[
+        str | None,
+        typer.Option(
+            "--resume",
+            "-r",
+            help="Attach to an existing session id instead of starting one.",
+        ),
+    ] = None,
+    role: Annotated[
+        str | None,
+        typer.Option("--role", help="Which agent this is, e.g. backend-dev."),
+    ] = None,
+    team: Annotated[
+        bool,
+        typer.Option("--team", help="Headless only: turn team mode on."),
+    ] = False,
+    transport: Annotated[
+        str | None, typer.Option("--transport", help="unix | tcp.")
+    ] = None,
+    socket: Annotated[
+        str | None, typer.Option("--socket", help="Unix socket path.")
+    ] = None,
+    host: Annotated[
+        str | None,
+        typer.Option("--host", help="TCP host to bind (headless) or connect to."),
+    ] = None,
+    port: Annotated[
+        int | None, typer.Option("--port", help="TCP port. Default 7717.")
+    ] = None,
+    version: Annotated[
+        bool, typer.Option("--version", help="Print the version and exit.")
+    ] = False,
+) -> None:
+    """Start stcode. With no subcommand this is the whole program."""
+    if version:
+        typer.echo(f"stcode {__version__}")
+        raise typer.Exit()
+    if ctx.invoked_subcommand is not None:
+        ctx.obj = _address(transport, socket, host, port), config
+        return
+    if headless and daemonless:
+        _fail(
+            "--headless and --daemonless are opposites: one is the daemon without a UI, "
+            "the other the UI without a daemon."
+        )
+    approval_mode = _mode(mode)
+
+    if headless:
+        # Flags pass through by name: `stcode-daemon` is the one that understands them.
+        flags = {
+            "--config": config,
+            "--transport": transport,
+            "--socket": socket,
+            "--host": host,
+            "--port": port,
+            "--mode": approval_mode,
+            "--role": role,
+        }
+        command = daemon_command()
+        command += [
+            str(item)
+            for flag, value in flags.items()
+            if value is not None
+            for item in (flag, value)
+        ]
+        command += ["--team"] if team else []
+        os.execv(command[0], command)
+
+    # Resolved, not kept as typed: `.` reaches the prefs file as the trusted path, the
+    # daemon as the session's cwd and the UI as the root it lists files under, and a
+    # relative one means something different in each of them.
+    cwd = cwd.expanduser().resolve() if cwd is not None else None
+    if cwd is not None and not cwd.is_dir():
+        _fail(f"{cwd} is not a directory.")
+
+    # Imported lazily: `stcode sessions` shouldn't pay for loading textual.
+    from stcode.cli.bootstrap import run
+
+    run(
+        Launcher(_address(transport, socket, host, port), config=config),
+        daemonless=daemonless,
+        restart=restart,
+        cwd=cwd,
+        resume=resume or "",
+        mode=approval_mode,
+        role=role or "",
+    )
+
+
+def _address(
+    transport: str | None, socket: str | None, host: str | None, port: int | None
+) -> Address:
+    address = Address(transport=transport or "unix")
+    if socket:
+        address.socket = Path(socket).expanduser()
+    address.host = host or address.host
+    address.port = port or address.port
+    return address
+
+
+def _fail(message: str) -> NoReturn:
+    typer.secho(message, fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=2)
+
+
+def _mode(value: str | None) -> ApprovalMode | None:
+    """Resolve `--mode auto` to a mode name, or exit saying what the choices are."""
+    if value is None:
+        return None
+    resolved = parse_approval_mode(value)
+    if resolved is None:
+        _fail(f"Unknown mode {value!r}. One of: {', '.join(APPROVAL_MODES)}")
+    return resolved
+
+
+def _with_daemon(
+    ctx: typer.Context, action: Callable[[DaemonClient], Awaitable[None]]
+) -> None:
+    """Run one request against the daemon, starting it for the duration if needed."""
+    address, config = ctx.obj
+
+    async def go() -> None:
+        launcher = Launcher(address, config=config)
+        try:
+            client = await launcher.connect()
+        except (OSError, DaemonFailed) as exc:
+            _fail(f"Could not reach a daemon at {address}: {exc}")
+        try:
+            async with client:
+                await action(client)
+        finally:
+            await launcher.stop()
+
+    asyncio.run(go())
+
+
+@cli.command("sessions")
+def list_sessions(
+    ctx: typer.Context,
+    limit: Annotated[int, typer.Option("--limit", "-n", help="How many to show.")] = 20,
+) -> None:
+    """List recent sessions, newest first. Resume one with `stcode --resume <id>`."""
+
+    async def show(client: DaemonClient) -> None:
+        rows = await client.sessions(limit)
+        if not rows:
+            typer.echo("No sessions yet.")
+        for row in rows:
+            typer.echo(
+                f"{row.get('id', '?'):<28} {row.get('ts', ''):<26} {row.get('cwd', '')}"
+            )
+
+    _with_daemon(ctx, show)
+
+
+@cli.command("config")
+def show_config(ctx: typer.Context) -> None:
+    """Show the daemon's config file and what it currently selects."""
+
+    async def show(client: DaemonClient) -> None:
+        frame: dict[str, Any] = await client.get_config()
+        typer.echo(f"path:     {frame.get('path')}")
+        typer.echo(f"provider: {frame.get('provider')}")
+        typer.echo(f"model:    {frame.get('model')}")
+        typer.echo(f"effort:   {frame.get('reasoning_effort')}")
+        typer.echo(f"mode:     {frame.get('approval_mode')}")
+        typer.echo(f"daemon:   {ctx.obj[0]}")
+
+    _with_daemon(ctx, show)
+
+
+def workspace_argv(argv: list[str], commands: set[str]) -> list[str]:
+    """Rewrite a leading path into `--cwd <path>`. Everything else is untouched.
+
+    The first token only, and only when it is neither a flag nor a subcommand. A token
+    that is neither but also does not look like a path — `stcode sesions` — is left
+    alone, so a mistyped command still gets click's "No such command" instead of being
+    silently accepted as a directory that does not exist.
+    """
+    if not argv:
+        return argv
+    first = argv[0]
+    if first.startswith("-") or first in commands:
+        return argv
+    looks_like_a_path = (
+        Path(first).expanduser().is_dir()
+        or first.startswith(("~", ".", "/"))
+        or "/" in first
+    )
+    if not looks_like_a_path:
+        return argv
+    return ["--cwd", first, *argv[1:]]
+
+
+def run_cli() -> None:
+    """The console entry point. → `workspace_argv`."""
+    commands = set(typer.main.get_command(cli).commands)  # type: ignore[attr-defined]
+    cli(args=workspace_argv(sys.argv[1:], commands))
+
+
+if __name__ == "__main__":
+    run_cli()

stcode/cli/models.py

@@ -0,0 +1,61 @@
+"""Client-owned vocabulary and values; never imports the engine or terminal UI."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+from pydantic import BaseModel, Field
+
+ApprovalMode = Literal["plan", "suggest", "auto-edit", "full-auto"]
+APPROVAL_MODES: tuple[ApprovalMode, ...] = ("plan", "suggest", "auto-edit", "full-auto")
+REASONING_EFFORTS = ("none", "minimal", "low", "medium", "high", "xhigh", "max")
+Row = tuple[str, str]
+ThemePreference = Literal["auto", "dark", "light"]
+THEME_PREFERENCES: tuple[ThemePreference, ...] = ("auto", "dark", "light")
+DEFAULT_THEME: ThemePreference = "auto"
+DEFAULT_SHELL_TIMEOUT = 10.0
+MAX_SHELL_TIMEOUT = 120.0
+
+
+@dataclass(frozen=True)
+class StartOptions:
+    cwd: Path
+    explicit_cwd: bool = False
+    daemonless: bool = False
+    resume: str = ""
+    mode: ApprovalMode | None = None
+    role: str = ""
+
+
+class UiPrefs(BaseModel):
+    """What the terminal remembers between runs."""
+
+    theme: ThemePreference = DEFAULT_THEME
+    trusted: list[str] = Field(default_factory=list)
+    """Absolute paths the user has approved the agent working in. A folder's children
+    are covered by it — a project has subdirectories, and asking again for each one
+    trains people to click through the question."""
+
+    shell_timeout: float = DEFAULT_SHELL_TIMEOUT
+    """Seconds a `!` command may run before it is killed. Capped at
+    `MAX_SHELL_TIMEOUT`. A client preference sent with each daemon workspace command;
+    the command never enters the agent's history."""
+
+    def is_trusted(self, path: str | Path) -> bool:
+        """Whether `path`, or a parent of it, has been trusted.
+
+        Compared as paths, not as strings: `startswith` would let `/home/me/work`
+        trust `/home/me/work-other`, which is a different project.
+        """
+        target = Path(path).expanduser().resolve()
+        for entry in self.trusted:
+            root = Path(entry).expanduser()
+            if target == root or root in target.parents:
+                return True
+        return False
+
+    def trust(self, path: str | Path) -> None:
+        """Approve `path`. Idempotent, and stored resolved so `.` never gets in."""
+        resolved = str(Path(path).expanduser().resolve())
+        if resolved not in self.trusted:
+            self.trusted.append(resolved)