yee88 0.3.0__py3-none-any.whl

yee88/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

yee88/api.py

@@ -0,0 +1,116 @@
+"""Stable public API for Takopi plugins."""
+
+from __future__ import annotations
+
+from .backends import EngineBackend, EngineConfig, SetupIssue
+from .commands import (
+    CommandBackend,
+    CommandContext,
+    CommandExecutor,
+    CommandResult,
+    RunMode,
+    RunRequest,
+    RunResult,
+)
+from .config import ConfigError
+from .context import RunContext
+from .directives import DirectiveError
+from .events import EventFactory
+from .model import (
+    Action,
+    ActionEvent,
+    CompletedEvent,
+    EngineId,
+    ResumeToken,
+    StartedEvent,
+)
+from .presenter import Presenter
+from .progress import ActionState, ProgressState, ProgressTracker
+from .router import RunnerUnavailableError
+from .runner import BaseRunner, JsonlSubprocessRunner, Runner
+from .runner_bridge import (
+    ExecBridgeConfig,
+    IncomingMessage,
+    RunningTask,
+    RunningTasks,
+    handle_message,
+)
+from .transport import MessageRef, RenderedMessage, SendOptions, Transport
+from .transport_runtime import ResolvedMessage, ResolvedRunner, TransportRuntime
+from .transports import SetupResult, TransportBackend
+
+from .config import HOME_CONFIG_PATH, read_config, write_config
+from .ids import RESERVED_COMMAND_IDS
+from .logging import bind_run_context, clear_context, get_logger, suppress_logs
+from .utils.paths import reset_run_base_dir, set_run_base_dir
+from .scheduler import ThreadJob, ThreadScheduler
+from .commands import get_command, list_command_ids
+from .engines import list_backends
+from .settings import load_settings
+from .backends_helpers import install_issue
+
+TAKOPI_PLUGIN_API_VERSION = 1
+
+__all__ = [
+    # Core types
+    "Action",
+    "ActionEvent",
+    "BaseRunner",
+    "CompletedEvent",
+    "ConfigError",
+    "CommandBackend",
+    "CommandContext",
+    "CommandExecutor",
+    "CommandResult",
+    "EngineBackend",
+    "EngineConfig",
+    "EngineId",
+    "ExecBridgeConfig",
+    "EventFactory",
+    "IncomingMessage",
+    "JsonlSubprocessRunner",
+    "MessageRef",
+    "DirectiveError",
+    "Presenter",
+    "ProgressState",
+    "ProgressTracker",
+    "ActionState",
+    "RenderedMessage",
+    "ResumeToken",
+    "RunMode",
+    "RunRequest",
+    "RunResult",
+    "ResolvedMessage",
+    "ResolvedRunner",
+    "RunContext",
+    "Runner",
+    "RunnerUnavailableError",
+    "RunningTask",
+    "RunningTasks",
+    "SendOptions",
+    "SetupIssue",
+    "SetupResult",
+    "StartedEvent",
+    "TAKOPI_PLUGIN_API_VERSION",
+    "Transport",
+    "TransportBackend",
+    "TransportRuntime",
+    "handle_message",
+    "HOME_CONFIG_PATH",
+    "RESERVED_COMMAND_IDS",
+    "read_config",
+    "write_config",
+    "get_logger",
+    "bind_run_context",
+    "clear_context",
+    "suppress_logs",
+    "set_run_base_dir",
+    "reset_run_base_dir",
+    "ThreadJob",
+    "ThreadScheduler",
+    "get_command",
+    "list_command_ids",
+    "list_backends",
+    "load_settings",
+    "install_issue",
+]

yee88/backends.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .runner import Runner
+
+EngineConfig = dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class SetupIssue:
+    title: str
+    lines: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class EngineBackend:
+    id: str
+    build_runner: Callable[[EngineConfig, Path], Runner]
+    cli_cmd: str | None = None
+    install_cmd: str | None = None

yee88/backends_helpers.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from .backends import SetupIssue
+
+
+def install_issue(cmd: str, install_cmd: str | None) -> SetupIssue:
+    if install_cmd:
+        lines = (f"   [dim]$[/] {install_cmd}",)
+    else:
+        lines = ("   [dim]See engine setup docs for install instructions.[/]",)
+    return SetupIssue(
+        f"install {cmd}",
+        lines,
+    )

yee88/cli/__init__.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+# ruff: noqa: F401
+
+from collections.abc import Callable
+import sys
+from pathlib import Path
+
+import typer
+
+from .. import __version__
+from ..config import (
+    ConfigError,
+    HOME_CONFIG_PATH,
+    load_or_init_config,
+    write_config,
+)
+from ..config_migrations import migrate_config
+from ..commands import get_command
+from ..engines import get_backend, list_backend_ids
+from ..ids import RESERVED_CHAT_COMMANDS, RESERVED_COMMAND_IDS, RESERVED_ENGINE_IDS
+from ..lockfile import LockError, LockHandle, acquire_lock, token_fingerprint
+from ..logging import setup_logging
+from ..runtime_loader import build_runtime_spec, resolve_plugins_allowlist
+from ..settings import (
+    TakopiSettings,
+    load_settings,
+    load_settings_if_exists,
+    validate_settings_data,
+)
+from ..plugins import (
+    COMMAND_GROUP,
+    ENGINE_GROUP,
+    TRANSPORT_GROUP,
+    entrypoint_distribution_name,
+    get_load_errors,
+    is_entrypoint_allowed,
+    list_entrypoints,
+    normalize_allowlist,
+)
+from ..transports import get_transport
+from ..utils.git import resolve_default_base, resolve_main_worktree_root
+from ..telegram import onboarding
+from ..telegram.client import TelegramClient
+from ..telegram.topics import _validate_topics_setup_for
+from .doctor import (
+    DoctorCheck,
+    DoctorStatus,
+    _doctor_file_checks,
+    _doctor_telegram_checks,
+    _doctor_voice_checks,
+    run_doctor,
+)
+from .init import (
+    _default_alias_from_path,
+    _ensure_projects_table,
+    _prompt_alias,
+    run_init,
+)
+from .onboarding_cmd import chat_id, onboarding_paths
+from .topic import run_topic
+from .plugins import plugins_cmd
+from .run import (
+    _default_engine_for_setup,
+    _print_version_and_exit,
+    _resolve_setup_engine,
+    _resolve_transport_id,
+    _run_auto_router,
+    _setup_needs_config,
+    _should_run_interactive,
+    _version_callback,
+    acquire_config_lock,
+    app_main,
+    make_engine_cmd,
+)
+from .config import (
+    _CONFIG_PATH_OPTION,
+    _config_path_display,
+    _exit_config_error,
+    _fail_missing_config,
+    _flatten_config,
+    _load_config_or_exit,
+    _normalized_value_from_settings,
+    _parse_key_path,
+    _parse_value,
+    _resolve_config_path_override,
+    _toml_literal,
+    config_get,
+    config_list,
+    config_path_cmd,
+    config_set,
+    config_unset,
+)
+
+
+def _load_settings_optional() -> tuple[TakopiSettings | None, Path | None]:
+    try:
+        loaded = load_settings_if_exists()
+    except ConfigError:
+        return None, None
+    if loaded is None:
+        return None, None
+    return loaded
+
+
+def init(
+    alias: str | None = typer.Argument(
+        None, help="Project alias (used as /alias in messages)."
+    ),
+    default: bool = typer.Option(
+        False,
+        "--default",
+        help="Set this project as the default_project.",
+    ),
+) -> None:
+    """Register the current repo as a Takopi project."""
+    run_init(
+        alias=alias,
+        default=default,
+        load_or_init_config_fn=load_or_init_config,
+        resolve_main_worktree_root_fn=resolve_main_worktree_root,
+        resolve_default_base_fn=resolve_default_base,
+        list_backend_ids_fn=list_backend_ids,
+        resolve_plugins_allowlist_fn=resolve_plugins_allowlist,
+    )
+
+
+def topic_init(
+    project: str | None = typer.Argument(
+        None, help="Project alias (defaults to current directory name)."
+    ),
+    branch: str | None = typer.Option(
+        None, "--branch", "-b", help="Branch name (defaults to current git branch)."
+    ),
+) -> None:
+    """Create a Telegram topic bound to a project/branch."""
+    run_topic(
+        project=project,
+        branch=branch,
+        delete=False,
+        config_path=None,
+    )
+
+
+def topic_delete(
+    project: str | None = typer.Argument(
+        None, help="Project alias (defaults to current directory name)."
+    ),
+    branch: str | None = typer.Option(
+        None, "--branch", "-b", help="Branch name (defaults to current git branch)."
+    ),
+) -> None:
+    """Delete a Telegram topic binding."""
+    run_topic(
+        project=project,
+        branch=branch,
+        delete=True,
+        config_path=None,
+    )
+
+
+def doctor() -> None:
+    """Run configuration checks for the active transport."""
+    setup_logging(debug=False, cache_logger_on_first_use=False)
+    run_doctor(
+        load_settings_fn=load_settings,
+        telegram_checks=_doctor_telegram_checks,
+        file_checks=_doctor_file_checks,
+        voice_checks=_doctor_voice_checks,
+    )
+
+
+def _engine_ids_for_cli() -> list[str]:
+    allowlist: list[str] | None = None
+    try:
+        config, _ = load_or_init_config()
+    except ConfigError:
+        return list_backend_ids()
+    raw_plugins = config.get("plugins")
+    if isinstance(raw_plugins, dict):
+        enabled = raw_plugins.get("enabled")
+        if isinstance(enabled, list):
+            allowlist = [
+                value.strip()
+                for value in enabled
+                if isinstance(value, str) and value.strip()
+            ]
+            if not allowlist:
+                allowlist = None
+    return list_backend_ids(allowlist=allowlist)
+
+
+def create_app() -> typer.Typer:
+    app = typer.Typer(
+        add_completion=False,
+        invoke_without_command=True,
+        help="Telegram bridge for coding agents. Docs: https://yee88.dev/",
+    )
+    config_app = typer.Typer(help="Read and modify yee88 config.")
+    config_app.command(name="path")(config_path_cmd)
+    config_app.command(name="list")(config_list)
+    config_app.command(name="get")(config_get)
+    config_app.command(name="set")(config_set)
+    config_app.command(name="unset")(config_unset)
+    topic_app = typer.Typer(help="Manage Telegram topics.")
+    topic_app.command(name="init")(topic_init)
+    topic_app.command(name="delete")(topic_delete)
+    app.command(name="init")(init)
+    app.add_typer(topic_app, name="topic")
+    app.command(name="chat-id")(chat_id)
+    app.command(name="doctor")(doctor)
+    app.command(name="onboarding-paths")(onboarding_paths)
+    app.command(name="plugins")(plugins_cmd)
+    app.add_typer(config_app, name="config")
+    app.callback()(app_main)
+    for engine_id in _engine_ids_for_cli():
+        help_text = f"Run with the {engine_id} engine."
+        app.command(name=engine_id, help=help_text)(make_engine_cmd(engine_id))
+    return app
+
+
+def main() -> None:
+    app = create_app()
+    app()
+
+
+if __name__ == "__main__":
+    main()

yee88/cli/config.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+import re
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import typer
+from pydantic import BaseModel
+
+from ..config import (
+    ConfigError,
+    HOME_CONFIG_PATH,
+    dump_toml,
+    read_config,
+    write_config,
+)
+from ..config_migrations import migrate_config
+from ..settings import TakopiSettings, validate_settings_data
+
+_KEY_SEGMENT_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+_MISSING = object()
+_CONFIG_PATH_OPTION = typer.Option(
+    None,
+    "--config-path",
+    help="Override the default config path.",
+)
+
+
+def _config_path_display(path: Path) -> str:
+    home = Path.home()
+    try:
+        return f"~/{path.relative_to(home)}"
+    except ValueError:
+        return str(path)
+
+
+def _fail_missing_config(path: Path) -> None:
+    display = _config_path_display(path)
+    if path.exists():
+        typer.echo(f"error: invalid yee88 config at {display}", err=True)
+    else:
+        typer.echo(f"error: missing yee88 config at {display}", err=True)
+
+
+def _resolve_config_path_override(value: Path | None) -> Path:
+    if value is None:
+        return _resolve_home_config_path()
+    return value.expanduser()
+
+
+def _resolve_home_config_path() -> Path:
+    cli_module = sys.modules.get("yee88.cli")
+    if cli_module is not None:
+        override = getattr(cli_module, "HOME_CONFIG_PATH", None)
+        if override is not None:
+            return Path(override)
+    return HOME_CONFIG_PATH
+
+
+def _exit_config_error(exc: ConfigError, *, code: int = 2) -> None:
+    typer.echo(f"error: {exc}", err=True)
+    raise typer.Exit(code=code) from exc
+
+
+def _parse_key_path(raw: str) -> list[str]:
+    value = raw.strip()
+    if not value:
+        raise ConfigError("Invalid key path; expected a non-empty value.")
+    segments = value.split(".")
+    for segment in segments:
+        if not segment:
+            raise ConfigError(f"Invalid key path {raw!r}; empty segment.")
+        if not _KEY_SEGMENT_RE.fullmatch(segment):
+            raise ConfigError(
+                f"Invalid key segment {segment!r} in {raw!r}; "
+                "use only letters, numbers, '_' or '-'."
+            )
+    return segments
+
+
+def _parse_value(raw: str) -> Any:
+    value = raw.strip()
+    if not value:
+        return ""
+    try:
+        return tomllib.loads(f"__v__ = {value}")["__v__"]
+    except tomllib.TOMLDecodeError:
+        return value
+
+
+def _toml_literal(value: Any) -> str:
+    dumped = dump_toml({"__v__": value})
+    prefix = "__v__ = "
+    if dumped.startswith(prefix):
+        return dumped[len(prefix) :].rstrip("\n")
+    raise ConfigError("Unsupported config value; unable to render TOML literal.")
+
+
+def _normalized_value_from_settings(
+    settings: TakopiSettings, segments: list[str]
+) -> Any:
+    node: Any = settings
+    for segment in segments:
+        if isinstance(node, BaseModel):
+            if segment in node.__class__.model_fields:
+                node = getattr(node, segment)
+            else:
+                extra = node.model_extra or {}
+                node = extra.get(segment, _MISSING)
+        elif isinstance(node, dict):
+            node = node.get(segment, _MISSING)
+        else:
+            return _MISSING
+        if node is _MISSING:
+            return _MISSING
+    if isinstance(node, BaseModel):
+        return node.model_dump(exclude_unset=True)
+    return node
+
+
+def _flatten_config(config: dict[str, Any]) -> list[tuple[str, Any]]:
+    items: list[tuple[str, Any]] = []
+
+    def _walk(node: Any, prefix: str) -> None:
+        if isinstance(node, dict):
+            for key in sorted(node):
+                value = node[key]
+                path = f"{prefix}.{key}" if prefix else key
+                if isinstance(value, dict):
+                    _walk(value, path)
+                else:
+                    items.append((path, value))
+        elif prefix:
+            items.append((prefix, node))
+
+    _walk(config, "")
+    return items
+
+
+def _load_config_or_exit(path: Path, *, missing_code: int) -> dict[str, Any]:
+    if not path.exists():
+        _fail_missing_config(path)
+        raise typer.Exit(code=missing_code)
+    try:
+        return read_config(path)
+    except ConfigError as exc:
+        _exit_config_error(exc)
+    return {}
+
+
+def config_path_cmd(
+    config_path: Path | None = _CONFIG_PATH_OPTION,
+) -> None:
+    """Print the resolved config path."""
+    path = _resolve_config_path_override(config_path)
+    typer.echo(_config_path_display(path))
+
+
+def config_list(
+    config_path: Path | None = _CONFIG_PATH_OPTION,
+) -> None:
+    """List config keys as flattened dot-paths."""
+    path = _resolve_config_path_override(config_path)
+    config = _load_config_or_exit(path, missing_code=1)
+    try:
+        for key, value in _flatten_config(config):
+            literal = _toml_literal(value)
+            typer.echo(f"{key} = {literal}")
+    except ConfigError as exc:
+        _exit_config_error(exc)
+
+
+def config_get(
+    key: str = typer.Argument(..., help="Dot-path key to fetch."),
+    config_path: Path | None = _CONFIG_PATH_OPTION,
+) -> None:
+    """Fetch a single config key."""
+    path = _resolve_config_path_override(config_path)
+    config = _load_config_or_exit(path, missing_code=2)
+    try:
+        segments = _parse_key_path(key)
+    except ConfigError as exc:
+        _exit_config_error(exc)
+
+    node: Any = config
+    for index, segment in enumerate(segments):
+        if not isinstance(node, dict):
+            prefix = ".".join(segments[:index])
+            _exit_config_error(
+                ConfigError(f"Invalid `{prefix}` in {path}; expected a table.")
+            )
+        if segment not in node:
+            raise typer.Exit(code=1)
+        node = node[segment]
+
+    if isinstance(node, dict):
+        typer.echo(
+            f"error: {'.'.join(segments)!r} is a table; pick a leaf node.",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    try:
+        typer.echo(_toml_literal(node))
+    except ConfigError as exc:
+        _exit_config_error(exc)
+
+
+def config_set(
+    key: str = typer.Argument(..., help="Dot-path key to set."),
+    value: str = typer.Argument(..., help="Value to assign (auto-parsed)."),
+    config_path: Path | None = _CONFIG_PATH_OPTION,
+) -> None:
+    """Set a config value."""
+    path = _resolve_config_path_override(config_path)
+    config = _load_config_or_exit(path, missing_code=2)
+    try:
+        segments = _parse_key_path(key)
+    except ConfigError as exc:
+        _exit_config_error(exc)
+
+    try:
+        migrate_config(config, config_path=path)
+    except ConfigError as exc:
+        _exit_config_error(exc)
+
+    parsed = _parse_value(value)
+    node: Any = config
+    for index, segment in enumerate(segments[:-1]):
+        next_node = node.get(segment)
+        if next_node is None:
+            created: dict[str, Any] = {}
+            node[segment] = created
+            node = created
+            continue
+        if not isinstance(next_node, dict):
+            prefix = ".".join(segments[: index + 1])
+            _exit_config_error(
+                ConfigError(f"Invalid `{prefix}` in {path}; expected a table.")
+            )
+        node = next_node
+    node[segments[-1]] = parsed
+
+    try:
+        settings = validate_settings_data(config, config_path=path)
+    except ConfigError as exc:
+        _exit_config_error(exc)
+
+    normalized = _normalized_value_from_settings(settings, segments)
+    if normalized is not _MISSING:
+        node[segments[-1]] = normalized
+        parsed = normalized
+
+    try:
+        write_config(config, path)
+    except ConfigError as exc:
+        _exit_config_error(exc)
+
+    rendered = _toml_literal(parsed)
+    typer.echo(f"updated {'.'.join(segments)} = {rendered}")
+
+
+def config_unset(
+    key: str = typer.Argument(..., help="Dot-path key to remove."),
+    config_path: Path | None = _CONFIG_PATH_OPTION,
+) -> None:
+    """Remove a config key."""
+    path = _resolve_config_path_override(config_path)
+    config = _load_config_or_exit(path, missing_code=2)
+    try:
+        segments = _parse_key_path(key)
+    except ConfigError as exc:
+        _exit_config_error(exc)
+
+    try:
+        migrate_config(config, config_path=path)
+    except ConfigError as exc:
+        _exit_config_error(exc)
+
+    node: Any = config
+    stack: list[tuple[dict[str, Any], str]] = []
+    for index, segment in enumerate(segments[:-1]):
+        if not isinstance(node, dict):
+            prefix = ".".join(segments[:index])
+            _exit_config_error(
+                ConfigError(f"Invalid `{prefix}` in {path}; expected a table.")
+            )
+        next_node = node.get(segment)
+        if next_node is None:
+            raise typer.Exit(code=1)
+        if not isinstance(next_node, dict):
+            prefix = ".".join(segments[: index + 1])
+            _exit_config_error(
+                ConfigError(f"Invalid `{prefix}` in {path}; expected a table.")
+            )
+        stack.append((node, segment))
+        node = next_node
+
+    if not isinstance(node, dict):
+        prefix = ".".join(segments[:-1])
+        _exit_config_error(
+            ConfigError(f"Invalid `{prefix}` in {path}; expected a table.")
+        )
+    leaf = segments[-1]
+    if leaf not in node:
+        raise typer.Exit(code=1)
+    node.pop(leaf, None)
+
+    while stack and not node:
+        parent, key_name = stack.pop()
+        parent.pop(key_name, None)
+        node = parent
+
+    try:
+        validate_settings_data(config, config_path=path)
+        write_config(config, path)
+    except ConfigError as exc:
+        _exit_config_error(exc)