handoff-cli 0.3.0__py3-none-any.whl

cli/__init__.py

@@ -0,0 +1,3 @@
+"""handoff CLI package."""
+
+__version__ = "0.3.0"

cli/backend.py

@@ -0,0 +1,224 @@
+"""Backend resolution and command building for handoff.
+
+Given a resolved backend configuration (merged from type_defaults[<type>] + the
+backend's own fields in YAML), this module provides:
+
+  - set_backend_env(backend, ...): Set environment variables for the backend CLI
+  - build_args(backend, ...): Build the CLI argument list (claude or codex)
+
+Backend types:
+  claude — `claude -p ... --output-format stream-json` against any
+           anthropic-compatible endpoint; identity flags combine with
+           session_flags (`--session-id` fresh / `--resume` continuation).
+  codex  — `codex exec --json ...`; a fresh run takes session_flags alone
+           (codex assigns the thread id itself), a continuation uses
+           continue_id_flags *instead of* session_flags because
+           `codex exec resume` accepts a different flag set.
+
+Placeholder substitution:
+  {prompt}         — the prompt text
+  {session_id}     — session UUID / codex thread id
+  {system_prompt}  — configured system prompt
+  {model}          — resolved model name (backend's model or pro_model)
+  {pro_model}      — backend's pro_model
+  {cwd}            — working directory of the run
+  {home}           — $HOME
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional
+
+
+def _substitute(text: str, ctx: dict) -> str:
+    """Replace {placeholders} in a string using ctx dict."""
+    return text.format(**ctx)
+
+
+def _resolve_env_val(val, ctx: dict):
+    """Resolve a config value, handling strings with placeholders."""
+    if isinstance(val, str):
+        resolved = _substitute(val, ctx)
+        return os.path.expanduser(resolved)
+    return val
+
+
+def _base_ctx(backend: dict, model: str = "", pro_model: str = "", cwd: str = "") -> dict:
+    return {
+        "prompt": "",
+        "session_id": "",
+        "system_prompt": backend.get("_system_prompt", ""),
+        "model": model or backend.get("_resolved_model", ""),
+        "pro_model": pro_model or backend.get("pro_model", ""),
+        # legacy alias kept so old user configs with {default_model} don't crash
+        "default_model": model or backend.get("_resolved_model", ""),
+        "cwd": cwd,
+        "home": os.path.expanduser("~"),
+    }
+
+
+def backend_type(backend: dict) -> str:
+    return backend.get("type", "claude")
+
+
+# Inherited values of these would silently redirect a claude-type backend to
+# whatever endpoint/model the *calling* session uses. handoff is routinely
+# invoked from inside another claude session (e.g. dispatching opus from a
+# DeepSeek-proxied session), so that environment is always polluted — a
+# claude-type run must see only what its backend declares.
+_CLAUDE_HERMETIC_VARS = (
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_MODEL",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+    "CLAUDE_CODE_SUBAGENT_MODEL",
+)
+
+
+def set_backend_env(backend: dict, model: str, pro_model: str = ""):
+    """Set environment variables for the backend CLI.
+
+    Iterates the backend's 'env' mapping, substitutes placeholders,
+    and sets each key=value in os.environ. claude-type backends are hermetic:
+    known ANTHROPIC_*/model vars are cleared first, so only the backend's own
+    env block takes effect.
+    """
+    ctx = _base_ctx(backend, model=model, pro_model=pro_model)
+
+    if backend_type(backend) == "claude":
+        for key in _CLAUDE_HERMETIC_VARS:
+            os.environ.pop(key, None)
+
+    env_map = backend.get("env", {})
+    for key, val in env_map.items():
+        resolved = _resolve_env_val(val, ctx)
+        # an empty value (e.g. a model-less legacy backend resolving
+        # ANTHROPIC_MODEL="{model}") must not be exported — an empty env var
+        # breaks the CLI where an unset one would not
+        if resolved == "":
+            continue
+        os.environ[key] = resolved
+
+    # claude needs a config dir; codex backends have no ANTHROPIC_*/CLAUDE_* env
+    if backend_type(backend) == "claude":
+        if not os.environ.get("CLAUDE_CONFIG_DIR"):
+            os.environ["CLAUDE_CONFIG_DIR"] = os.path.expanduser("~/.claude")
+
+
+def build_args(
+    backend: dict,
+    prompt: str,
+    session_id: Optional[str] = None,
+    model: Optional[str] = None,
+    pro_model: Optional[str] = None,
+    resume: bool = False,
+    cwd: str = "",
+) -> list[str]:
+    """Build the backend CLI argument list from a resolved backend config.
+
+    claude type: session_flags carry -p/{prompt}/stream-json/etc.; when a
+    session_id is present, `continue_id_flags` (--resume, continuation) or
+    `session_id_flags` (--session-id, fresh) are appended on top.
+
+    codex type: a fresh run is session_flags alone (`codex exec --json ...`;
+    codex assigns the thread id itself, reported via the thread.started event).
+    A continuation is continue_id_flags alone (`codex exec resume --json <id>
+    <prompt>`) because `codex exec resume` rejects --sandbox/-C.
+    """
+    ctx = _base_ctx(backend, model=model or "", pro_model=pro_model or "", cwd=cwd)
+    ctx["prompt"] = prompt
+    ctx["session_id"] = session_id or ""
+
+    command = _resolve_env_val(backend.get("command") or backend.get("claude_command", "claude"), ctx)
+    args = [command]
+
+    if backend_type(backend) == "codex" and resume and session_id:
+        for flag in backend.get("continue_id_flags", []):
+            resolved = _resolve_env_val(flag, ctx)
+            if resolved:
+                args.append(resolved)
+        return args
+
+    for flag in backend.get("session_flags", []):
+        resolved = _resolve_env_val(flag, ctx)
+        if resolved:
+            args.append(resolved)
+
+    if session_id:
+        id_flags_key = "continue_id_flags" if resume else "session_id_flags"
+        for flag in backend.get(id_flags_key, []):
+            resolved = _resolve_env_val(flag, ctx)
+            if resolved:
+                args.append(resolved)
+
+    return args
+
+
+def wrap_with_pty(backend: dict, args: list[str]) -> list[str]:
+    """Prefix args with the configured PTY wrapper, if any."""
+    pty = backend.get("pty", [])
+    if not pty:
+        return args
+    ctx = _base_ctx(backend)
+    return [_resolve_env_val(part, ctx) for part in pty] + args
+
+
+def build_resume_args(
+    backend: dict,
+    session_id: str,
+    pro_model: Optional[str] = None,
+) -> list[str]:
+    """Build the interactive resume argument list (`claude --resume` / `codex resume`)."""
+    ctx = _base_ctx(backend, pro_model=pro_model or "")
+    ctx["session_id"] = session_id or ""
+
+    command = _resolve_env_val(backend.get("command") or backend.get("claude_command", "claude"), ctx)
+    args = [command]
+
+    for flag in backend.get("resume_flags", []):
+        resolved = _resolve_env_val(flag, ctx)
+        if resolved:
+            args.append(resolved)
+
+    return args
+
+
+def resolve_backend_model(backend: dict, is_pro: bool = False) -> str:
+    """Return the model name for this backend (its own model / pro_model field)."""
+    model = backend.get("pro_model" if is_pro else "model") or backend.get("model") or ""
+    ctx = {"home": os.path.expanduser("~")}
+    return _resolve_env_val(model, ctx) if model else ""
+
+
+def ensure_backend_token_ready(backend_name: str, backend: dict, user_config_path: str):
+    """Fail fast when the selected backend declares a token that isn't usable.
+
+    Only applies to backends whose env carries ANTHROPIC_AUTH_TOKEN (e.g. the
+    bundled deepseek). Backends that ride on local login state (opus, codex)
+    declare no token and are skipped. An empty value typically means an
+    unexpanded ${ENV_VAR} reference (variable not set in the environment).
+    """
+    env_map = backend.get("env", {})
+    if "ANTHROPIC_AUTH_TOKEN" not in env_map:
+        return
+    token = env_map.get("ANTHROPIC_AUTH_TOKEN")
+    if isinstance(token, str) and token.startswith("<"):
+        print(
+            f"handoff: backend '{backend_name}' still uses placeholder token {token}. "
+            f"Edit {user_config_path} and set a real ANTHROPIC_AUTH_TOKEN.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    if not token:
+        print(
+            f"handoff: backend '{backend_name}' has an empty ANTHROPIC_AUTH_TOKEN. "
+            f"Set it in {user_config_path}, or export the environment variable it "
+            f"references (e.g. DEEPSEEK_API_KEY).",
+            file=sys.stderr,
+        )
+        sys.exit(2)

cli/backend_types.yaml

@@ -0,0 +1,91 @@
+# handoff backend types — this file defines HOW each backend type is launched.
+# It is part of the program's behaviour and CANNOT be overridden by user config.
+# To understand the complete configuration model, start here.
+#
+# Types:
+#   claude — PTY-wrapped `claude -p --output-format stream-json` against any
+#            Anthropic-compatible endpoint.
+#   codex  — `codex exec --json` against the local codex login state.
+#
+# Each type defines the CLI command, PTY wrapper, and flag templates.
+# Placeholders ({model}, {prompt}, {session_id}, {system_prompt}, {cwd}, {home})
+# are substituted at runtime.
+#
+# User-owned configuration (backends, env, models) lives in ~/.handoff/config.yaml
+# (generated by `handoff init`). Run `handoff env` to locate both files.
+
+# System prompt appended to every claude invocation (claude-type backends only).
+# This is the one built-in value users CAN override — set `system_prompt:` in
+# ~/.handoff/config.yaml to replace it.
+system_prompt: |
+  重要：你收到的是一个完整需求，必须直接执行到底。禁止以下行为：
+  1. 不要分析完问题后问用户"要开始改吗？""倾向于哪个方案？"等确认
+  2. 不要提出多个方案让用户选择
+  3. 不要输出分析报告后停下来等指示
+  你需要：理解需求 → 直接修改代码 → 输出结果。需求模糊时按最合理的默认方式执行，不要问。
+
+types:
+  # ── claude type: PTY-wrapped `claude -p --output-format stream-json` ─────────
+  claude:
+    command: "claude"
+    pty:
+      - "script"
+      - "-q"
+      - "/dev/null"
+    session_flags:
+      - "-p"
+      - "{prompt}"
+      - "--dangerously-skip-permissions"
+      - "--append-system-prompt"
+      - "{system_prompt}"
+      - "--output-format"
+      - "stream-json"
+      - "--verbose"
+      - "--include-partial-messages"
+    session_id_flags:
+      - "--session-id"
+      - "{session_id}"
+    # Used by `resume <seq> <prompt>` (non-interactive continuation): append a new
+    # turn to an existing claude session in print mode. Combined with session_flags
+    # (which carry -p/{prompt}/stream-json/etc.) this becomes `claude -p ... --resume <id>`.
+    continue_id_flags:
+      - "--resume"
+      - "{session_id}"
+    resume_flags:
+      - "--resume"
+      - "{session_id}"
+      - "--dangerously-skip-permissions"
+
+  # ── codex type: `codex exec --json` against local codex login ─────────────────
+  codex:
+    command: "codex"
+    pty: []
+    # Fresh run: codex exec --json <flags> {prompt}
+    session_flags:
+      - "exec"
+      - "--json"
+      - "--skip-git-repo-check"
+      - "--sandbox"
+      - "workspace-write"
+      - "-m"
+      - "{model}"
+      - "-C"
+      - "{cwd}"
+      - "{prompt}"
+    # codex has no separate "set session id" mode for a fresh run; the id is
+    # assigned by codex and reported in the thread.started event.
+    session_id_flags: []
+    # Non-interactive continuation: codex exec resume --json <session_id> {prompt}.
+    # NOTE: `codex exec resume` does not accept --sandbox/-C; it inherits the
+    # original session's settings, so this list deliberately omits them.
+    continue_id_flags:
+      - "exec"
+      - "resume"
+      - "--json"
+      - "--skip-git-repo-check"
+      - "{session_id}"
+      - "{prompt}"
+    # Interactive reopen: `codex resume <session_id>`.
+    resume_flags:
+      - "resume"
+      - "{session_id}"

cli/commands/env.py

@@ -0,0 +1,30 @@
+"""handoff env command — print configuration paths for humans and scripts."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def cmd_env(_args):
+    """handoff env — print key configuration paths (no Config init needed)."""
+    if _args and _args[0] in ("-h", "--help"):
+        print("usage: handoff env")
+        print("  Print key configuration paths for use by humans and scripts.")
+        return
+
+    from ..config import user_config_dir, user_config_path
+
+    # backend_types.yaml lives alongside this file in the package
+    backend_types_path = os.path.join(os.path.dirname(__file__), "..", "backend_types.yaml")
+    backend_types_path = os.path.abspath(backend_types_path)
+
+    config = user_config_path()
+    tasks = os.path.join(user_config_dir(), "tasks")
+    runs = os.path.join(user_config_dir(), "runs")
+
+    # Print paths unconditionally — env must work even with a broken config.
+    print(f"config={config}")
+    print(f"backend_types={backend_types_path}")
+    print(f"tasks={tasks}          # prompt / .out / .result files")
+    print(f"runs={runs}            # raw jsonl streams")

cli/commands/init.py

@@ -0,0 +1,129 @@
+"""Interactive initializer for handoff."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def _pkg_root() -> str:
+    """Absolute path to the cli/ package directory."""
+    return os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+
+def _repo_root() -> str:
+    """Absolute path to the repo root (for README hint only; may not exist in a wheel install)."""
+    return os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+
+
+def _home_path(*parts: str) -> str:
+    return os.path.join(os.path.expanduser("~"), *parts)
+
+
+def _color(code: str, text: str) -> str:
+    if not sys.stdout.isatty() or os.environ.get("NO_COLOR"):
+        return text
+    return f"\033[{code}m{text}\033[0m"
+
+
+def _planned_writes() -> list[tuple[str, str, str]]:
+    skills_dir = os.path.join(_pkg_root(), "skills")
+    from ..config import user_config_path
+
+    plans: list[tuple[str, str, str]] = [
+        ("config", "write if missing", user_config_path()),
+    ]
+
+    plans += [
+        ("hard link", os.path.join(skills_dir, "handoff-ds.toml"), _home_path(".codex", "agents", "handoff-ds.toml")),
+        ("soft link", os.path.join(skills_dir, "handoff-ds", "SKILL.md"), _home_path(".claude", "skills", "handoff-ds", "SKILL.md")),
+        ("soft link", os.path.join(skills_dir, "handoff-codex", "SKILL.md"), _home_path(".claude", "skills", "handoff-codex", "SKILL.md")),
+        ("soft link", os.path.join(skills_dir, "handoff-opus", "SKILL.md"), _home_path(".claude", "skills", "handoff-opus", "SKILL.md")),
+    ]
+    return plans
+
+
+def _print_plan():
+    print(_color("1", "handoff initialization"))
+    print("")
+    print("The following files and links will be written:")
+    for kind, src, dest in _planned_writes():
+        if kind == "config":
+            if os.path.isfile(dest):
+                print(f"  config: keep existing {dest}")
+            else:
+                print(f"  config: write {dest}")
+        else:
+            print(f"  {kind}: {dest} -> {src}")
+    print("")
+
+
+def _confirm() -> bool:
+    _print_plan()
+    try:
+        answer = input("Type Y to continue, anything else to exit: ").strip()
+    except EOFError:
+        answer = ""
+    return answer.lower() == "y"
+
+
+def _create_links():
+    """Create hard/soft links for agent and skill files from cli/skills/."""
+    skills_dir = os.path.join(_pkg_root(), "skills")
+
+    # Hard link for Codex agent
+    src_agent = os.path.join(skills_dir, "handoff-ds.toml")
+    dest_agent = _home_path(".codex", "agents", "handoff-ds.toml")
+    os.makedirs(os.path.dirname(dest_agent), exist_ok=True)
+    if os.path.exists(dest_agent):
+        os.remove(dest_agent)
+    os.link(src_agent, dest_agent)
+    print(f"hard link: {dest_agent} <=> {src_agent}")
+
+    # Soft links for Claude Code skills (3 backends)
+    for skill_name in ("handoff-ds", "handoff-codex", "handoff-opus"):
+        src_skill = os.path.join(skills_dir, skill_name, "SKILL.md")
+        dest_skill_dir = _home_path(".claude", "skills", skill_name)
+        dest_skill = os.path.join(dest_skill_dir, "SKILL.md")
+        os.makedirs(dest_skill_dir, exist_ok=True)
+        if os.path.exists(dest_skill):
+            os.remove(dest_skill)
+        os.symlink(src_skill, dest_skill)
+        print(f"soft link: {dest_skill} -> {src_skill}")
+
+
+def run_init(assume_yes: bool = False):
+    if not assume_yes and not _confirm():
+        print("handoff: initialization cancelled")
+        sys.exit(1)
+
+    print("")
+    from ..config import user_config_path, write_default_user_config
+
+    wrote_config = write_default_user_config()
+    if wrote_config:
+        print(f"config: wrote {user_config_path()}")
+    else:
+        print(f"config: kept existing {user_config_path()}")
+
+    _create_links()
+
+    readme = os.path.join(_repo_root(), "README.md")
+
+    print("")
+    print("Next:")
+    print(f"  1. Set DEEPSEEK_API_KEY in your shell, or edit {user_config_path()} and replace ${{DEEPSEEK_API_KEY}} with your token.")
+    print(f"  2. Read {readme} for Codex and Claude Code usage.")
+
+
+def cmd_init(args):
+    if args and args[0] in ("-h", "--help"):
+        print("usage: handoff init [-y|--yes]")
+        return
+    assume_yes = False
+    for arg in args:
+        if arg in ("-y", "--yes"):
+            assume_yes = True
+        else:
+            print(f"handoff: init: unexpected argument '{arg}'", file=sys.stderr)
+            sys.exit(2)
+    run_init(assume_yes=assume_yes)

cli/commands/list.py

@@ -0,0 +1,81 @@
+"""handoff list command."""
+
+import os
+import sys
+
+from ..core import get_db, format_run_row
+from ..config import Config
+
+
+def cmd_list(argv: list[str], config: Config):
+    """handoff list [--uuid] [--cwd]"""
+    show_uuid = False
+    full_cwd = False
+
+    for a in argv:
+        if a == "--uuid":
+            show_uuid = True
+        elif a == "--cwd":
+            full_cwd = True
+        elif a in ("-h", "--help"):
+            from ..main import usage
+            usage()
+            sys.exit(0)
+        else:
+            print(f"handoff list: unknown argument {a}", file=sys.stderr)
+            sys.exit(2)
+
+    conn = get_db()
+    rows = conn.execute(
+        "SELECT seq, run_id, uuid, cwd, prompt, created_at, jsonl_path, status, backend "
+        "FROM runs ORDER BY created_at DESC LIMIT 50"
+    ).fetchall()
+
+    if not rows:
+        conn.close()
+        print("(no runs)")
+        return
+
+    if sys.stdin.isatty() and sys.stdout.isatty():
+        # Launch the TUI directly (textual is a package dependency now).
+        from ..tui import RunListApp
+
+        def _refresh_rows():
+            """Re-query the DB for the latest 50 runs.  Called by the TUI timer."""
+            return conn.execute(
+                "SELECT seq, run_id, uuid, cwd, prompt, created_at, jsonl_path, status, backend "
+                "FROM runs ORDER BY created_at DESC LIMIT 50"
+            ).fetchall()
+
+        app = RunListApp(rows, full_cwd, refresh_fn=_refresh_rows)
+        app.run(mouse=False)
+        conn.close()
+
+        # If the user pressed G (resume), handle it in this process so that
+        # _resume_interactive's os.execvp replaces us — the tty is inherited.
+        if app.action_result and app.action_result.startswith("resume:"):
+            run_id = app.action_result[len("resume:"):]
+            from .resume import cmd_resume
+            cmd_resume([run_id], config)
+        return
+
+    conn.close()
+
+    header = ["RUN", "DATE", "PROMPT", "CWD"]
+    if show_uuid:
+        header.append("UUID")
+
+    lines = ["  ".join(header)]
+    for r in rows:
+        fmt = format_run_row(r, full_cwd)
+        cols = [
+            fmt["id"].ljust(13),
+            fmt["date"].ljust(11),
+            fmt["prompt"].ljust(30),
+            fmt["cwd"],
+        ]
+        if show_uuid:
+            cols.append(fmt["uuid"])
+        lines.append("  ".join(cols))
+
+    print("\n".join(lines))