chatmd 0.2.7__py3-none-any.whl

chatmd/__init__.py

@@ -0,0 +1,3 @@
+"""ChatMD — A local-first, text-driven personal AI Agent engine."""
+
+__version__ = "0.2.7"

chatmd/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running chatmd as `python -m chatmd`."""
+
+from chatmd.cli import main
+
+if __name__ == "__main__":
+    main()

chatmd/cli.py

@@ -0,0 +1,214 @@
+"""ChatMD CLI entry point using Click."""
+
+from __future__ import annotations
+
+import io
+import os
+import sys
+
+import click
+
+from chatmd import __version__
+
+
+def _ensure_utf8_stdout() -> None:
+    """Reconfigure stdout/stderr to UTF-8 on Windows to avoid GBK encoding errors."""
+    if sys.platform == "win32":
+        os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+        if hasattr(sys.stdout, "reconfigure"):
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        else:
+            sys.stdout = io.TextIOWrapper(
+                sys.stdout.buffer, encoding="utf-8", errors="replace"
+            )
+        if hasattr(sys.stderr, "reconfigure"):
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        else:
+            sys.stderr = io.TextIOWrapper(
+                sys.stderr.buffer, encoding="utf-8", errors="replace"
+            )
+
+
+_ensure_utf8_stdout()
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="chatmd")
+def main() -> None:
+    """ChatMD — A local-first, text-driven personal AI Agent engine."""
+
+
+@main.command()
+@click.argument("path", type=click.Path())
+@click.option("--no-git", is_flag=True, default=False, help="Skip Git initialization.")
+def init(path: str, no_git: bool) -> None:
+    """Initialize a ChatMD workspace at PATH."""
+    from chatmd.commands.init_workspace import run_init
+
+    run_init(path, no_git=no_git)
+
+
+@main.command()
+@click.option(
+    "--workspace",
+    "-w",
+    type=click.Path(exists=True),
+    default=".",
+    help="Workspace directory (default: current dir).",
+)
+@click.option(
+    "--daemon",
+    "-d",
+    is_flag=True,
+    default=False,
+    help="Run Agent in the background (detached process).",
+)
+def start(workspace: str, daemon: bool) -> None:
+    """Start the ChatMD Agent."""
+    from chatmd.commands.agent_lifecycle import run_start, run_start_daemon
+
+    if daemon:
+        run_start_daemon(workspace)
+    else:
+        run_start(workspace)
+
+
+@main.command()
+@click.option(
+    "--workspace",
+    "-w",
+    type=click.Path(exists=True),
+    default=".",
+    help="Workspace directory (default: current dir).",
+)
+def stop(workspace: str) -> None:
+    """Stop the ChatMD Agent."""
+    from chatmd.commands.agent_lifecycle import run_stop
+
+    run_stop(workspace)
+
+
+@main.command()
+@click.option(
+    "--workspace",
+    "-w",
+    type=click.Path(exists=True),
+    default=".",
+    help="Workspace directory (default: current dir).",
+)
+def status(workspace: str) -> None:
+    """Show Agent status."""
+    from chatmd.commands.agent_lifecycle import run_status
+
+    run_status(workspace)
+
+
+@main.command()
+@click.option(
+    "--workspace",
+    "-w",
+    type=click.Path(exists=True),
+    default=".",
+    help="Workspace directory (default: current dir).",
+)
+def restart(workspace: str) -> None:
+    """Restart the ChatMD Agent (stop + start daemon)."""
+    from chatmd.commands.agent_lifecycle import run_restart
+
+    run_restart(workspace)
+
+
+@main.command()
+@click.option(
+    "--workspace",
+    "-w",
+    type=click.Path(exists=True),
+    default=".",
+    help="Workspace directory (default: current dir).",
+)
+@click.option("--full", is_flag=True, default=False, help="Upgrade to full workspace mode.")
+def upgrade(workspace: str, full: bool) -> None:
+    """Upgrade an existing ChatMD workspace."""
+    from chatmd.commands.upgrade import run_upgrade
+
+    run_upgrade(workspace, full=full)
+
+
+@main.command()
+@click.argument("mode", type=click.Choice(["suffix", "save"]), required=False)
+@click.option(
+    "--workspace",
+    "-w",
+    type=click.Path(exists=True),
+    default=".",
+    help="Workspace directory (default: current dir).",
+)
+def mode(mode: str | None, workspace: str) -> None:
+    """Show or switch trigger mode (suffix / save)."""
+    from chatmd.commands.mode import run_mode
+
+    run_mode(workspace, mode)
+
+
+@main.group()
+def service() -> None:
+    """Manage system service (auto-start on boot)."""
+
+
+@service.command("install")
+@click.option(
+    "--workspace",
+    "-w",
+    type=click.Path(exists=True),
+    default=".",
+    help="Workspace directory (default: current dir).",
+)
+def service_install(workspace: str) -> None:
+    """Install ChatMD Agent as a system service."""
+    from chatmd.commands.service import run_service_install
+
+    run_service_install(workspace)
+
+
+@service.command("uninstall")
+@click.option(
+    "--workspace",
+    "-w",
+    type=click.Path(exists=True),
+    default=None,
+    help="Workspace directory. Omit to use --all.",
+)
+@click.option(
+    "--all",
+    "uninstall_all",
+    is_flag=True,
+    default=False,
+    help="Uninstall all ChatMD services.",
+)
+def service_uninstall(workspace: str | None, uninstall_all: bool) -> None:
+    """Uninstall ChatMD Agent system service."""
+    if uninstall_all:
+        from chatmd.commands.service import run_service_uninstall_all
+        run_service_uninstall_all()
+    elif workspace:
+        from chatmd.commands.service import run_service_uninstall
+        run_service_uninstall(workspace)
+    else:
+        # Default: uninstall current dir workspace
+        from chatmd.commands.service import run_service_uninstall
+        run_service_uninstall(".")
+
+
+@service.command("status")
+@click.option(
+    "--workspace",
+    "-w",
+    type=click.Path(exists=True),
+    default=None,
+    help="Workspace directory. Omit to list all services.",
+)
+def service_status(workspace: str | None) -> None:
+    """Show ChatMD Agent system service status."""
+    from chatmd.commands.service import run_service_status
+
+    run_service_status(workspace)

chatmd/commands/__init__.py

@@ -0,0 +1 @@
+"""ChatMD CLI command implementations."""

chatmd/commands/agent_lifecycle.py

@@ -0,0 +1,327 @@
+"""Agent lifecycle commands — start, stop, status."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+import click
+
+from chatmd.exceptions import AgentError
+from chatmd.i18n import t
+
+logger = logging.getLogger(__name__)
+
+
+def _is_process_alive(pid: int) -> bool:
+    """Check whether a process with *pid* is currently running (cross-platform)."""
+    if sys.platform == "win32":
+        import ctypes
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        query_limited = 0x1000
+        handle = kernel32.OpenProcess(query_limited, False, pid)
+        if handle:
+            kernel32.CloseHandle(handle)
+            return True
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+
+
+def _read_log_level(workspace: Path) -> int:
+    """Read ``logging.level`` from agent.yaml, defaulting to INFO."""
+    agent_yaml = workspace / ".chatmd" / "agent.yaml"
+    if agent_yaml.exists():
+        try:
+            import yaml
+            with open(agent_yaml, encoding="utf-8") as fh:
+                data = yaml.safe_load(fh) or {}
+            level_str = (data.get("logging") or {}).get("level", "INFO")
+            return getattr(logging, str(level_str).upper(), logging.INFO)
+        except Exception:
+            pass
+    return logging.INFO
+
+
+def _setup_logging(workspace: Path) -> None:
+    """Configure logging for the Agent process."""
+    log_dir = workspace / ".chatmd" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    file_level = _read_log_level(workspace)
+
+    root = logging.getLogger("chatmd")
+    root.setLevel(logging.DEBUG)
+
+    # Console handler — always INFO regardless of config
+    console = logging.StreamHandler(sys.stderr)
+    console.setLevel(logging.INFO)
+    console.setFormatter(logging.Formatter("%(levelname)s %(message)s"))
+    root.addHandler(console)
+
+    # File handler — respects logging.level from agent.yaml
+    fh = logging.FileHandler(log_dir / "agent.log", encoding="utf-8")
+    fh.setLevel(file_level)
+    fh.setFormatter(
+        logging.Formatter("%(asctime)s %(name)s %(levelname)s %(message)s")
+    )
+    root.addHandler(fh)
+
+
+def run_start(workspace_str: str) -> None:
+    """Start the ChatMD Agent in the foreground."""
+    workspace = Path(workspace_str).resolve()
+    chatmd_dir = workspace / ".chatmd"
+
+    if not chatmd_dir.is_dir():
+        click.echo(t("cli.not_workspace", workspace=workspace))
+        click.echo(t("cli.run_init_first"))
+        sys.exit(1)
+
+    _setup_logging(workspace)
+
+    from chatmd.engine.agent import Agent
+
+    try:
+        agent = Agent(workspace)
+        click.echo(t("cli.starting", workspace=workspace))
+        click.echo(t("cli.press_ctrl_c"))
+        agent.run_forever()
+    except AgentError as exc:
+        click.echo(f"❌ {exc}")
+        sys.exit(1)
+    except KeyboardInterrupt:
+        click.echo(t("cli.agent_stopped"))
+
+
+def run_start_daemon(workspace_str: str) -> None:
+    """Start the ChatMD Agent as a detached background process.
+
+    Spawns ``chatmd start -w <workspace>`` in a new detached process,
+    then the current (parent) process exits immediately.
+
+    Cross-platform:
+    - Windows: subprocess.CREATE_NO_WINDOW + CREATE_NEW_PROCESS_GROUP
+    - Unix: start_new_session=True (setsid)
+
+    Logs go to .chatmd/logs/agent.log (same as foreground mode).
+    """
+    import subprocess
+
+    workspace = Path(workspace_str).resolve()
+    chatmd_dir = workspace / ".chatmd"
+
+    if not chatmd_dir.is_dir():
+        click.echo(t("cli.not_workspace", workspace=workspace))
+        click.echo(t("cli.run_init_first"))
+        sys.exit(1)
+
+    # Check for existing instance via PID file
+    pid_file = chatmd_dir / "agent.pid"
+    if pid_file.exists():
+        try:
+            pid = int(pid_file.read_text(encoding="utf-8").strip())
+            if _is_process_alive(pid):
+                click.echo(t("cli.daemon_already_running", pid=pid))
+                return
+            pid_file.unlink(missing_ok=True)
+        except (ValueError, OSError):
+            pid_file.unlink(missing_ok=True)
+
+    # Build the command: re-invoke chatmd start (without --daemon) for this workspace
+    cmd = [sys.executable, "-m", "chatmd", "start", "-w", str(workspace)]
+
+    # Ensure log directory exists
+    log_dir = chatmd_dir / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / "agent.log"
+
+    # Inherit current env and force UTF-8 for the child process (avoids GBK crash on Windows)
+    env = {**os.environ, "PYTHONIOENCODING": "utf-8"}
+
+    if sys.platform == "win32":
+        # Windows: CREATE_NO_WINDOW prevents a console window from appearing
+        # CREATE_NEW_PROCESS_GROUP detaches from parent's console group
+        creation_flags = (
+            subprocess.CREATE_NO_WINDOW | subprocess.CREATE_NEW_PROCESS_GROUP
+        )
+        proc = subprocess.Popen(
+            cmd,
+            stdout=open(log_dir / "daemon_stdout.log", "a", encoding="utf-8"),
+            stderr=open(log_dir / "daemon_stderr.log", "a", encoding="utf-8"),
+            stdin=subprocess.DEVNULL,
+            creationflags=creation_flags,
+            env=env,
+        )
+    else:
+        # Unix: start_new_session=True calls setsid(), fully detaching
+        proc = subprocess.Popen(
+            cmd,
+            stdout=open(log_dir / "daemon_stdout.log", "a", encoding="utf-8"),
+            stderr=open(log_dir / "daemon_stderr.log", "a", encoding="utf-8"),
+            stdin=subprocess.DEVNULL,
+            start_new_session=True,
+            env=env,
+        )
+
+    # Wait briefly to check if the process started successfully
+    import time
+    time.sleep(0.5)
+
+    if proc.poll() is not None:
+        click.echo(t("cli.daemon_failed", code=proc.returncode))
+        sys.exit(1)
+
+    click.echo(t("cli.daemon_started", pid=proc.pid, workspace=workspace))
+    click.echo(t("cli.daemon_log_hint", log=log_file))
+    click.echo(t("cli.daemon_stop_hint"))
+
+
+def run_stop(workspace_str: str) -> None:
+    """Stop a running ChatMD Agent using a signal file (cross-platform).
+
+    Strategy:
+    1. Write .chatmd/stop.signal — the Agent main loop detects this and
+       shuts down gracefully (works on all platforms).
+    2. On Unix, also send SIGTERM as a belt-and-suspenders fallback.
+    3. Wait briefly for the process to exit, then clean up.
+    """
+    workspace = Path(workspace_str).resolve()
+    chatmd_dir = workspace / ".chatmd"
+    pid_file = chatmd_dir / "agent.pid"
+    stop_signal = chatmd_dir / "stop.signal"
+
+    if not pid_file.exists():
+        click.echo(t("cli.no_running_agent"))
+        return
+
+    try:
+        pid = int(pid_file.read_text(encoding="utf-8").strip())
+    except (ValueError, OSError):
+        click.echo(t("cli.pid_corrupted"))
+        pid_file.unlink(missing_ok=True)
+        return
+
+    # Verify the process is actually running before sending stop signal
+    if not _is_process_alive(pid):
+        click.echo(t("cli.process_not_found"))
+        pid_file.unlink(missing_ok=True)
+        stop_signal.unlink(missing_ok=True)
+        return
+
+    # 1. Write stop signal file (cross-platform, always works)
+    try:
+        stop_signal.write_text(str(pid), encoding="utf-8")
+    except OSError as exc:
+        logger.warning("Failed to write stop signal file: %s", exc)
+
+    # 2. On Unix, also send SIGTERM as fallback
+    if sys.platform != "win32":
+        try:
+            import signal
+            os.kill(pid, signal.SIGTERM)
+        except ProcessLookupError:
+            click.echo(t("cli.process_not_found"))
+            pid_file.unlink(missing_ok=True)
+            stop_signal.unlink(missing_ok=True)
+            return
+        except PermissionError:
+            click.echo(t("cli.no_permission", pid=pid))
+            return
+
+    # 3. Wait for process to exit (up to 5 seconds)
+    import time
+    for _ in range(10):
+        if not _is_process_alive(pid):
+            break
+        time.sleep(0.5)
+
+    click.echo(t("cli.stop_signal_sent", pid=pid))
+
+
+def run_restart(workspace_str: str) -> None:
+    """Restart the ChatMD Agent (stop then start as daemon).
+
+    Behaviour:
+    - If a daemon is running → stop it, then start a new daemon.
+    - If no daemon is running → just start a new daemon.
+    - Always restarts in daemon (background) mode.
+    """
+    workspace = Path(workspace_str).resolve()
+    chatmd_dir = workspace / ".chatmd"
+
+    if not chatmd_dir.is_dir():
+        click.echo(t("cli.not_workspace", workspace=workspace))
+        click.echo(t("cli.run_init_first"))
+        sys.exit(1)
+
+    pid_file = chatmd_dir / "agent.pid"
+    was_running = False
+
+    if pid_file.exists():
+        try:
+            pid = int(pid_file.read_text(encoding="utf-8").strip())
+            if _is_process_alive(pid):
+                was_running = True
+                click.echo(t("cli.restart_stopping", pid=pid))
+                run_stop(workspace_str)
+
+                # Wait for process to fully exit (up to 5s)
+                import time
+                for _ in range(10):
+                    if not _is_process_alive(pid):
+                        break
+                    time.sleep(0.5)
+        except (ValueError, OSError):
+            pid_file.unlink(missing_ok=True)
+
+    if was_running:
+        click.echo(t("cli.restart_starting"))
+    else:
+        click.echo(t("cli.restart_not_running"))
+
+    run_start_daemon(workspace_str)
+
+
+def run_status(workspace_str: str) -> None:
+    """Show Agent status."""
+    workspace = Path(workspace_str).resolve()
+    chatmd_dir = workspace / ".chatmd"
+
+    if not chatmd_dir.is_dir():
+        click.echo(t("cli.not_workspace", workspace=workspace))
+        return
+
+    pid_file = chatmd_dir / "agent.pid"
+    if not pid_file.exists():
+        click.echo(t("cli.agent_not_running"))
+        return
+
+    try:
+        pid = int(pid_file.read_text(encoding="utf-8").strip())
+    except (ValueError, OSError):
+        click.echo(t("cli.agent_not_running_stale"))
+        pid_file.unlink(missing_ok=True)
+        return
+
+    if _is_process_alive(pid):
+        click.echo(t("cli.agent_running", pid=pid))
+    else:
+        click.echo(t("cli.agent_not_running_stale"))
+        pid_file.unlink(missing_ok=True)
+
+    # Show workspace info
+    click.echo(t("cli.workspace_label", workspace=workspace))
+
+    skills_dir = chatmd_dir / "skills"
+    if skills_dir.exists():
+        yaml_count = len(list(skills_dir.glob("*.yaml")))
+        py_count = len(list(skills_dir.glob("*.py")))
+        click.echo(t("cli.custom_skills", yaml_count=yaml_count, py_count=py_count))