comate-cli 0.1.10__tar.gz → 0.2.0__tar.gz

{comate_cli-0.1.10 → comate_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comate-cli
-Version: 0.1.10
+Version: 0.2.0
 Summary: Comate terminal CLI built on comate-agent-sdk
 Project-URL: Homepage, https://github.com/AndyLee1024/agent-sdk
 Project-URL: Repository, https://github.com/AndyLee1024/agent-sdk

{comate_cli-0.1.10 → comate_cli-0.2.0}/comate_cli/mcp_cli.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import argparse
 import asyncio
 import sys
-from pathlib import Path
 from typing import Any
 
 from comate_agent_sdk.mcp import (
@@ -15,6 +14,7 @@ from comate_agent_sdk.mcp import (
     write_mcp_servers_to_path,
 )
 from comate_agent_sdk.mcp.types import McpServerConfig
+from comate_agent_sdk.utils.paths import PathInput
 
 
 class McpCliError(ValueError):
@@ -191,7 +191,7 @@ def _build_add_server_config(args: argparse.Namespace) -> McpServerConfig:
     return cfg  # type: ignore[return-value]
 
 
-def _load_servers_by_scope(*, scope: str, project_root: Path | None) -> dict[str, McpServerConfig]:
+def _load_servers_by_scope(*, scope: str, project_root: PathInput | None) -> dict[str, McpServerConfig]:
     if scope == "effective":
         return load_effective_servers(project_root=project_root)
     return load_scope_servers(scope=scope, project_root=project_root)  # type: ignore[arg-type]
@@ -200,7 +200,7 @@ def _load_servers_by_scope(*, scope: str, project_root: Path | None) -> dict[str
 def _read_effective_server_with_source(
     *,
     name: str,
-    project_root: Path | None,
+    project_root: PathInput | None,
 ) -> tuple[McpServerConfig, str] | None:
     user_servers = load_scope_servers(scope="user", project_root=project_root)
     project_servers = load_scope_servers(scope="project", project_root=project_root)
@@ -230,7 +230,7 @@ def _format_server_endpoint(cfg: McpServerConfig) -> str:
     return " ".join([command, *str_args]).strip()
 
 
-def _cmd_add(args: argparse.Namespace, *, project_root: Path | None) -> None:
+def _cmd_add(args: argparse.Namespace, *, project_root: PathInput | None) -> None:
     scope = str(args.scope)
     name = str(args.name).strip()
     if not name:
@@ -250,7 +250,7 @@ def _cmd_add(args: argparse.Namespace, *, project_root: Path | None) -> None:
     )
 
 
-def _cmd_remove(args: argparse.Namespace, *, project_root: Path | None) -> None:
+def _cmd_remove(args: argparse.Namespace, *, project_root: PathInput | None) -> None:
     scope = str(args.scope)
     name = str(args.name).strip()
     if not name:
@@ -271,7 +271,7 @@ def _cmd_remove(args: argparse.Namespace, *, project_root: Path | None) -> None:
     )
 
 
-def _cmd_list(args: argparse.Namespace, *, project_root: Path | None) -> None:
+def _cmd_list(args: argparse.Namespace, *, project_root: PathInput | None) -> None:
     scope = str(args.scope)
     servers = _load_servers_by_scope(scope=scope, project_root=project_root)
     if not servers:
@@ -295,7 +295,7 @@ def _cmd_list(args: argparse.Namespace, *, project_root: Path | None) -> None:
         sys.stdout.write(f"{alias}: {endpoint} ({server_type}) - {status}\n")
 
 
-def _cmd_get(args: argparse.Namespace, *, project_root: Path | None) -> None:
+def _cmd_get(args: argparse.Namespace, *, project_root: PathInput | None) -> None:
     name = str(args.name).strip()
     scope = str(args.scope)
     if not name:
@@ -363,7 +363,7 @@ def _cmd_get(args: argparse.Namespace, *, project_root: Path | None) -> None:
     sys.stdout.write("\n".join(lines) + "\n")
 
 
-def run_mcp_command(argv: list[str], *, project_root: Path | None = None) -> None:
+def run_mcp_command(argv: list[str], *, project_root: PathInput | None = None) -> None:
     parser = _build_parser()
     parsed, extra_args = parser.parse_known_args(argv)
     command = str(getattr(parsed, "command", "") or "").strip()

{comate_cli-0.1.10 → comate_cli-0.2.0}/comate_cli/terminal_agent/animations.py

@@ -11,26 +11,27 @@ from rich.text import Text
 from comate_agent_sdk.agent.events import StopEvent, TextEvent, ToolCallEvent, ToolResultEvent, UserQuestionEvent
 
 DEFAULT_STATUS_PHRASES: tuple[str, ...] = (
-    "Vibing...",
-    "Thinking...",
-    "Reasoning...",
-    "Planning next move...",
-    "Reading context...",
-    "Connecting dots...",
-    "Synthesizing signal...",
-    "Spotting edge cases...",
-    "Checking assumptions...",
-    "Tracing dependencies...",
-    "Drafting response...",
-    "Polishing details...",
-    "Validating flow...",
-    "Cross-checking facts...",
-    "Refining intent...",
-    "Mapping tools...",
-    "Building confidence...",
-    "Stitching answer...",
-    "Finalizing output...",
-    "Almost there...",
+    "Embellishing…",
+    "Vibing…",
+    "Thinking…",
+    "Reasoning…",
+    "Planning next move…",
+    "Reading context…",
+    "Connecting dots…",
+    "Synthesizing signal…",
+    "Spotting edge cases…",
+    "Checking assumptions…",
+    "Tracing dependencies…",
+    "Drafting response…",
+    "Polishing details…",
+    "Validating flow…",
+    "Cross-checking facts…",
+    "Refining intent…",
+    "Mapping tools…",
+    "Building confidence…",
+    "Stitching answer…",
+    "Finalizing output…",
+    "Almost there…",
 )
 
 BREATH_DOT_COLORS: tuple[str, ...] = (

{comate_cli-0.1.10 → comate_cli-0.2.0}/comate_cli/terminal_agent/app.py

@@ -5,6 +5,7 @@ import importlib.metadata
 import locale
 import logging
 import os
+import random
 import signal
 import threading
 import time
@@ -21,6 +22,7 @@ from comate_agent_sdk.tools import tool
 
 from comate_cli.terminal_agent.event_renderer import EventRenderer
 from comate_cli.terminal_agent.logo import print_logo
+from comate_cli.terminal_agent.tips import TIPS
 from comate_cli.terminal_agent.preflight import run_preflight_if_needed
 from comate_cli.terminal_agent.resume_selector import select_resume_session_id
 from comate_cli.terminal_agent.rpc_stdio import StdioRPCBridge
@@ -67,8 +69,8 @@ async def _check_update() -> str | None:
         return None
 
     if _is_chinese_locale():
-        url = f"https://mirrors.cloud.tencent.com/pypi/pypi/{package}/json"
-        source_label = "tencent"
+        url = f"https://mirrors.tuna.tsinghua.edu.cn/pypi/{package}/json"
+        source_label = "tuna"
     else:
         url = f"https://pypi.org/pypi/{package}/json"
         source_label = "pypi"
@@ -88,9 +90,9 @@ async def _check_update() -> str | None:
         from packaging.version import Version
         if Version(latest) > Version(current):
             return (
-                f"[dim]💡 New version available: [bold cyan]{latest}[/] "
+                f"[dim] New version available: [bold cyan]{latest}[/] "
                 f"(current: {current})  "
-                f"Run [bold]uv tool upgrade {package}[/] to upgrade.[/]"
+                f"Run [bold green]uv tool upgrade {package}[/] to upgrade.[/]"
             )
     except Exception:
         pass
@@ -282,6 +284,7 @@ async def run(
         return
 
     print_logo(console, project_root=project_root)
+    console.print(f"[dim]💡 Tip: {random.choice(TIPS)}[/dim]")
 
     if resume_select and not resume_session_id:
         selected_session_id = await select_resume_session_id(console, cwd=project_root)

comate_cli-0.2.0/comate_cli/terminal_agent/custom_slash_commands.py

@@ -0,0 +1,494 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+from comate_agent_sdk.utils.paths import PathInput, normalize_path_input
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_ITEM_MAX_BYTES = 32 * 1024
+DEFAULT_TOTAL_MAX_BYTES = 128 * 1024
+DEFAULT_BASH_TIMEOUT_SECONDS = 10.0
+
+_COMMAND_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9_-]+$")
+_ARG_PLACEHOLDER_PATTERN = re.compile(r"\$ARGUMENTS\[(\d+)\]|\$(\d+)|\$ARGUMENTS")
+_BASH_PATTERN = re.compile(r"!\`([^`\n]+)\`")
+_FILE_REF_PATTERN = re.compile(r"(?<!\S)@([^\s]+)")
+_MARKER_PREFIX = "<<__COMATE_CUSTOM_BLOCK_"
+_MARKER_SUFFIX = "__>>"
+
+
+class CustomSlashExpandError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class CustomSlashCommand:
+    name: str
+    description: str
+    template: str
+    source_scope: Literal["project", "user"]
+    namespace: str
+    source_path: Path
+    argument_hint: str | None = None
+
+    def scope_label(self) -> str:
+        if self.namespace:
+            return f"{self.source_scope}:{self.namespace}"
+        return self.source_scope
+
+    def description_with_scope(self) -> str:
+        return f"{self.description} [{self.scope_label()}]"
+
+
+@dataclass(frozen=True, slots=True)
+class CustomSlashLoadResult:
+    commands: tuple[CustomSlashCommand, ...]
+    warnings: tuple[str, ...]
+
+
+def discover_custom_slash_commands(
+    *,
+    project_root: PathInput,
+    builtin_names: set[str],
+    user_root: PathInput | None = None,
+) -> CustomSlashLoadResult:
+    resolved_project_root = normalize_path_input(project_root, field_name="project_root")
+    resolved_user_root = normalize_path_input(
+        user_root if user_root is not None else Path.home(),
+        field_name="user_root",
+    )
+
+    project_dir = resolved_project_root / ".agent" / "commands"
+    user_dir = resolved_user_root / ".agent" / "commands"
+
+    commands: list[CustomSlashCommand] = []
+    warnings: list[str] = []
+    loaded_by_name: dict[str, CustomSlashCommand] = {}
+
+    for scope, root in (("project", project_dir), ("user", user_dir)):
+        if not root.is_dir():
+            continue
+
+        per_scope_names: set[str] = set()
+        for file_path in sorted(root.rglob("*.md")):
+            parsed = _parse_custom_command_file(file_path=file_path, scope=scope, root_dir=root)
+            if isinstance(parsed, str):
+                warnings.append(parsed)
+                continue
+
+            name = parsed.name
+            if name in builtin_names:
+                warnings.append(
+                    f"Skipped custom command '/{name}' from {file_path}: conflicts with builtin command name."
+                )
+                continue
+
+            if name in per_scope_names:
+                warnings.append(
+                    f"Skipped custom command '/{name}' from {file_path}: duplicate name in {scope} scope."
+                )
+                continue
+            per_scope_names.add(name)
+
+            if name in loaded_by_name:
+                existing = loaded_by_name[name]
+                warnings.append(
+                    f"Skipped custom command '/{name}' from {file_path}: already provided by "
+                    f"{existing.source_scope} scope ({existing.source_path})."
+                )
+                continue
+
+            loaded_by_name[name] = parsed
+            commands.append(parsed)
+
+    commands.sort(key=lambda item: item.name.lower())
+    return CustomSlashLoadResult(commands=tuple(commands), warnings=tuple(warnings))
+
+
+def _parse_custom_command_file(
+    *,
+    file_path: Path,
+    scope: Literal["project", "user"],
+    root_dir: Path,
+) -> CustomSlashCommand | str:
+    command_name = file_path.stem.strip()
+    if not command_name or _COMMAND_NAME_PATTERN.fullmatch(command_name) is None:
+        return (
+            f"Skipped custom command from {file_path}: invalid filename '{file_path.stem}'. "
+            "Only [a-zA-Z0-9_-] is allowed."
+        )
+
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return f"Skipped custom command '/{command_name}' from {file_path}: read failed ({exc})."
+
+    if not content.startswith("---"):
+        return (
+            f"Skipped custom command '/{command_name}' from {file_path}: missing YAML frontmatter."
+        )
+
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        return (
+            f"Skipped custom command '/{command_name}' from {file_path}: invalid frontmatter format."
+        )
+
+    try:
+        frontmatter = yaml.safe_load(parts[1]) or {}
+    except Exception as exc:
+        return (
+            f"Skipped custom command '/{command_name}' from {file_path}: frontmatter parse failed ({exc})."
+        )
+
+    if not isinstance(frontmatter, dict):
+        return (
+            f"Skipped custom command '/{command_name}' from {file_path}: frontmatter must be a map."
+        )
+
+    raw_description = frontmatter.get("description")
+    description = str(raw_description).strip() if isinstance(raw_description, str) else ""
+    if not description:
+        return (
+            f"Skipped custom command '/{command_name}' from {file_path}: missing required 'description'."
+        )
+
+    raw_argument_hint = frontmatter.get("argument-hint", frontmatter.get("argument_hint"))
+    argument_hint = str(raw_argument_hint).strip() if isinstance(raw_argument_hint, str) else ""
+    if not argument_hint:
+        argument_hint = _extract_argument_hint(parts[1]) or ""
+    if not argument_hint:
+        argument_hint = None
+
+    template = parts[2].strip()
+    if not template:
+        return (
+            f"Skipped custom command '/{command_name}' from {file_path}: empty command template body."
+        )
+
+    namespace_path = file_path.parent.relative_to(root_dir).as_posix()
+    namespace = "" if namespace_path in {"", "."} else namespace_path
+
+    return CustomSlashCommand(
+        name=command_name,
+        description=description,
+        template=template,
+        source_scope=scope,
+        namespace=namespace,
+        source_path=file_path,
+        argument_hint=argument_hint,
+    )
+
+
+async def render_custom_slash_prompt(
+    *,
+    command: CustomSlashCommand,
+    raw_args: str,
+    project_root: PathInput,
+    item_max_bytes: int = DEFAULT_ITEM_MAX_BYTES,
+    total_max_bytes: int = DEFAULT_TOTAL_MAX_BYTES,
+    bash_timeout_seconds: float = DEFAULT_BASH_TIMEOUT_SECONDS,
+) -> str:
+    resolved_project_root = normalize_path_input(project_root, field_name="project_root")
+    normalized_args = raw_args.strip()
+    try:
+        arg_tokens = shlex.split(normalized_args) if normalized_args else []
+    except ValueError as exc:
+        raise CustomSlashExpandError(f"Failed to parse arguments: {exc}") from exc
+
+    replaced_text, used_arg_placeholder = _replace_argument_placeholders(
+        template=command.template,
+        raw_args=normalized_args,
+        arg_tokens=arg_tokens,
+    )
+    if normalized_args and not used_arg_placeholder:
+        replaced_text = f"{replaced_text.rstrip()}\n\nARGUMENTS: {normalized_args}"
+
+    marker_map: dict[str, str] = {}
+    total_inserted_bytes = 0
+
+    after_bash = await _replace_bash_markers(
+        text=replaced_text,
+        marker_map=marker_map,
+        project_root=resolved_project_root,
+        item_max_bytes=item_max_bytes,
+        total_max_bytes=total_max_bytes,
+        total_inserted_bytes=total_inserted_bytes,
+        bash_timeout_seconds=bash_timeout_seconds,
+    )
+    total_inserted_bytes = _marker_payload_size(marker_map)
+
+    after_file_ref = _replace_file_reference_markers(
+        text=after_bash,
+        marker_map=marker_map,
+        project_root=resolved_project_root,
+        item_max_bytes=item_max_bytes,
+        total_max_bytes=total_max_bytes,
+        total_inserted_bytes=total_inserted_bytes,
+    )
+
+    rendered = after_file_ref
+    for marker, block in marker_map.items():
+        rendered = rendered.replace(marker, block)
+
+    return rendered
+
+
+def _replace_argument_placeholders(
+    *,
+    template: str,
+    raw_args: str,
+    arg_tokens: list[str],
+) -> tuple[str, bool]:
+    used_placeholder = False
+
+    def _replace(match: re.Match[str]) -> str:
+        nonlocal used_placeholder
+        used_placeholder = True
+
+        indexed_argument = match.group(1)
+        shorthand_argument = match.group(2)
+
+        if indexed_argument is not None:
+            index = int(indexed_argument)
+            if index >= len(arg_tokens):
+                raise CustomSlashExpandError(
+                    f"Missing required argument at position {index + 1} for placeholder "
+                    f"$ARGUMENTS[{index}]."
+                )
+            return arg_tokens[index]
+
+        if shorthand_argument is not None:
+            index = int(shorthand_argument) - 1
+            if index < 0 or index >= len(arg_tokens):
+                raise CustomSlashExpandError(
+                    f"Missing required argument for placeholder ${shorthand_argument}."
+                )
+            return arg_tokens[index]
+
+        return raw_args
+
+    try:
+        rendered = _ARG_PLACEHOLDER_PATTERN.sub(_replace, template)
+    except CustomSlashExpandError:
+        raise
+
+    return rendered, used_placeholder
+
+
+async def _replace_bash_markers(
+    *,
+    text: str,
+    marker_map: dict[str, str],
+    project_root: Path,
+    item_max_bytes: int,
+    total_max_bytes: int,
+    total_inserted_bytes: int,
+    bash_timeout_seconds: float,
+) -> str:
+    if not text:
+        return text
+
+    parts: list[str] = []
+    cursor = 0
+    marker_index = len(marker_map)
+
+    for match in _BASH_PATTERN.finditer(text):
+        parts.append(text[cursor : match.start()])
+        command = match.group(1).strip()
+        if not command:
+            raise CustomSlashExpandError("Empty bash command in !`...` block.")
+
+        output = await _run_bash_command(
+            command=command,
+            cwd=project_root,
+            timeout_seconds=bash_timeout_seconds,
+        )
+        output_bytes = len(output.encode("utf-8"))
+        if output_bytes > item_max_bytes:
+            raise CustomSlashExpandError(
+                f"Bash output exceeds {item_max_bytes} bytes for command: {command}"
+            )
+
+        block = _format_bash_output_block(command=command, output=output)
+        block_bytes = len(block.encode("utf-8"))
+        total_inserted_bytes += block_bytes
+        if total_inserted_bytes > total_max_bytes:
+            raise CustomSlashExpandError(
+                f"Expanded custom command exceeds total limit ({total_max_bytes} bytes)."
+            )
+
+        marker = f"{_MARKER_PREFIX}{marker_index}{_MARKER_SUFFIX}"
+        marker_map[marker] = block
+        marker_index += 1
+        parts.append(marker)
+        cursor = match.end()
+
+    parts.append(text[cursor:])
+    return "".join(parts)
+
+
+def _replace_file_reference_markers(
+    *,
+    text: str,
+    marker_map: dict[str, str],
+    project_root: Path,
+    item_max_bytes: int,
+    total_max_bytes: int,
+    total_inserted_bytes: int,
+) -> str:
+    if not text:
+        return text
+
+    resolved_project_root = project_root.expanduser().resolve()
+    parts: list[str] = []
+    cursor = 0
+    marker_index = len(marker_map)
+
+    for match in _FILE_REF_PATTERN.finditer(text):
+        parts.append(text[cursor : match.start()])
+        raw_path = match.group(1).strip()
+        if not raw_path:
+            raise CustomSlashExpandError("Empty file reference after '@'.")
+        if raw_path.startswith("~"):
+            raise CustomSlashExpandError(f"File reference must be relative to project root: @{raw_path}")
+
+        target = Path(raw_path)
+        if target.is_absolute():
+            raise CustomSlashExpandError(f"Absolute file reference is not allowed: @{raw_path}")
+
+        candidate = (resolved_project_root / target).resolve()
+        if not _is_path_under_root(candidate, resolved_project_root):
+            raise CustomSlashExpandError(f"File reference escapes project root: @{raw_path}")
+        if not candidate.is_file():
+            raise CustomSlashExpandError(f"File not found for reference: @{raw_path}")
+
+        try:
+            payload = candidate.read_bytes()
+        except OSError as exc:
+            raise CustomSlashExpandError(f"Failed to read file for reference @{raw_path}: {exc}") from exc
+
+        if b"\x00" in payload:
+            raise CustomSlashExpandError(f"Binary file is not supported for reference: @{raw_path}")
+        if len(payload) > item_max_bytes:
+            raise CustomSlashExpandError(
+                f"Referenced file exceeds {item_max_bytes} bytes: @{raw_path}"
+            )
+
+        try:
+            content = payload.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise CustomSlashExpandError(
+                f"Referenced file must be UTF-8 text: @{raw_path}"
+            ) from exc
+
+        block = _format_file_reference_block(path=raw_path, content=content)
+        block_bytes = len(block.encode("utf-8"))
+        total_inserted_bytes += block_bytes
+        if total_inserted_bytes > total_max_bytes:
+            raise CustomSlashExpandError(
+                f"Expanded custom command exceeds total limit ({total_max_bytes} bytes)."
+            )
+
+        marker = f"{_MARKER_PREFIX}{marker_index}{_MARKER_SUFFIX}"
+        marker_map[marker] = block
+        marker_index += 1
+        parts.append(marker)
+        cursor = match.end()
+
+    parts.append(text[cursor:])
+    return "".join(parts)
+
+
+async def _run_bash_command(
+    *,
+    command: str,
+    cwd: Path,
+    timeout_seconds: float,
+) -> str:
+    process = await asyncio.create_subprocess_exec(
+        "/bin/bash",
+        "-lc",
+        command,
+        cwd=str(cwd),
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+    try:
+        stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout_seconds)
+    except asyncio.TimeoutError as exc:
+        process.kill()
+        await process.communicate()
+        raise CustomSlashExpandError(
+            f"Bash command timed out after {timeout_seconds:.1f}s: {command}"
+        ) from exc
+
+    stdout_text = stdout.decode("utf-8", errors="replace")
+    stderr_text = stderr.decode("utf-8", errors="replace")
+    merged_output = stdout_text.strip()
+    if stderr_text.strip():
+        merged_output = f"{merged_output}\n{stderr_text.strip()}".strip()
+    if not merged_output:
+        merged_output = "(no output)"
+
+    if process.returncode != 0:
+        raise CustomSlashExpandError(
+            f"Bash command failed (exit {process.returncode}): {command}\n{merged_output}"
+        )
+
+    return merged_output
+
+
+def _format_bash_output_block(*, command: str, output: str) -> str:
+    return (
+        "### Bash Command Output\n"
+        f"`{command}`\n"
+        "```text\n"
+        f"{output}\n"
+        "```"
+    )
+
+
+def _format_file_reference_block(*, path: str, content: str) -> str:
+    return (
+        "### File Content\n"
+        f"`{path}`\n"
+        "```text\n"
+        f"{content}\n"
+        "```"
+    )
+
+
+def _is_path_under_root(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def _marker_payload_size(marker_map: dict[str, str]) -> int:
+    return sum(len(item.encode("utf-8")) for item in marker_map.values())
+
+
+def _extract_argument_hint(frontmatter_text: str) -> str | None:
+    match = re.search(
+        r"(?mi)^\s*argument[-_]hint\s*:\s*(.+?)\s*$",
+        frontmatter_text,
+    )
+    if match is None:
+        return None
+    raw = match.group(1).strip()
+    if raw.startswith(("'", '"')) and raw.endswith(("'", '"')) and len(raw) >= 2:
+        raw = raw[1:-1].strip()
+    return raw or None