handoff-cli 0.3.0__py3-none-any.whl

cli/config.py

@@ -0,0 +1,351 @@
+"""YAML configuration loading and merging for handoff.
+
+Configuration is split into two layers:
+
+  1. Mechanism (cli/backend_types.yaml) — HOW each backend type is launched
+     (command, PTY, flag templates).  Bundled with the package; NOT overridable
+     by user config.  This is the program's behavioural contract.
+
+  2. Data (~/.handoff/config.yaml) — user-owned backends, models, env vars.
+     Generated by `handoff init` from the bundled template; the sole source of
+     backend definitions.  No hidden merge layers — what you see is what runs.
+
+Backend resolution:
+  - Resolved backend = types[<type>] (mechanism) + the backend's own fields (data)
+  - Deep-merge for mappings; lists are replaced wholesale (not concatenated)
+  - The first backend in the user config is the default (dict insertion order).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import copy
+from typing import Optional
+
+try:
+    import yaml
+except ImportError:
+    print(
+        "handoff: PyYAML is required. Install it with: pip install pyyaml",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+_BACKEND_TYPES_PATH = os.path.join(os.path.dirname(__file__), "backend_types.yaml")
+_USER_CONFIG_TEMPLATE_PATH = os.path.join(os.path.dirname(__file__), "user_config_template.yaml")
+
+# Top-level config keys that belong to the mechanism layer or are otherwise
+# removed.  Warn once and ignore.  system_prompt is deliberately absent from
+# this list — users CAN override it.
+_DEPRECATED_KEYS = (
+    "type_defaults", "backend_types", "backend_template",
+    "fast_backend", "default_model", "pro_model", "default_backend",
+)
+
+_TEMPLATE_URL = "https://github.com/dazuiba/handoff/blob/main/cli/user_config_template.yaml"
+
+
+def user_config_dir() -> str:
+    return os.path.join(os.path.expanduser("~"), ".handoff")
+
+
+def user_config_path() -> str:
+    return os.path.join(user_config_dir(), "config.yaml")
+
+
+def _load_yaml(path: str) -> dict:
+    """Load a YAML file, returning an empty dict if not found."""
+    if not os.path.isfile(path):
+        return {}
+    try:
+        with open(path, "r") as f:
+            data = yaml.safe_load(f) or {}
+        if not isinstance(data, dict):
+            print(f"handoff: config {path} must be a mapping", file=sys.stderr)
+            sys.exit(1)
+        return data
+    except yaml.YAMLError as e:
+        print(f"handoff: error parsing {path}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def write_default_user_config() -> bool:
+    """Copy the bundled template to ~/.handoff/config.yaml if missing.
+    Return True when written.
+    """
+    path = user_config_path()
+    if os.path.isfile(path):
+        return False
+
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(_USER_CONFIG_TEMPLATE_PATH, "r") as src:
+            content = src.read()
+        with open(path, "w") as dst:
+            dst.write(content)
+        return True
+    except OSError as e:
+        print(f"handoff: failed to create default user config at {path}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _ensure_user_config_exists():
+    if os.path.isfile(user_config_path()):
+        return
+
+    from .commands.init import run_init
+
+    run_init()
+    if not os.path.isfile(user_config_path()):
+        print(f"handoff: initialization did not create {user_config_path()}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Recursively merge override into base, return new dict."""
+    result = copy.deepcopy(base)
+    for key, val in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(val, dict):
+            result[key] = _deep_merge(result[key], val)
+        else:
+            result[key] = copy.deepcopy(val)
+    return result
+
+
+_ENV_VAR_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def _expand_env_vars(value):
+    """Recursively expand ${ENV_VAR} references in config string values.
+
+    Unset variables expand to the empty string (later caught by
+    ensure_backend_token_ready when a real token is required).
+    """
+    if isinstance(value, str):
+        return _ENV_VAR_RE.sub(lambda m: os.environ.get(m.group(1), ""), value)
+    if isinstance(value, dict):
+        return {k: _expand_env_vars(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_expand_env_vars(v) for v in value]
+    return value
+
+
+def _resolve_include_path(include_val: str, including_file_dir: str) -> str:
+    """Resolve an include path.
+
+    Absolute paths are used as-is.
+    Relative paths: first try relative to the including file's directory,
+    then fall back to the package directory.
+    """
+    if os.path.isabs(include_val):
+        return include_val
+
+    # Try relative to the including file's directory first
+    candidate = os.path.join(including_file_dir, include_val)
+    if os.path.isfile(candidate):
+        return candidate
+
+    # Fall back to the package directory
+    candidate = os.path.join(os.path.dirname(__file__), include_val)
+    if os.path.isfile(candidate):
+        return candidate
+
+    return candidate
+
+
+def _load_with_includes(path: str, _seen: Optional[set] = None) -> dict:
+    """Load a YAML file, recursively resolving `include:` directives.
+
+    `include` can be a string (single path) or list of paths.
+    Included files are deep-merged first (in order), then the current
+    file's own keys are deep-merged on top so they override includes.
+
+    Absolute include paths are used as-is.  Relative paths are resolved
+    against the including file's directory first, then the package dir.
+
+    _seen tracks already-visited paths to guard against cycles.
+    """
+    if _seen is None:
+        _seen = set()
+
+    real = os.path.realpath(path)
+    if real in _seen:
+        return {}
+    _seen.add(real)
+
+    data = _load_yaml(path)
+    includes = data.pop("include", None)
+    if isinstance(includes, str):
+        includes = [includes]
+    elif includes is None:
+        includes = []
+
+    including_dir = os.path.dirname(path)
+
+    # Deep-merge all includes first
+    merged = {}
+    for inc in includes:
+        inc_path = _resolve_include_path(inc, including_dir)
+        if os.path.isfile(inc_path):
+            inc_data = _load_with_includes(inc_path, _seen)
+            merged = _deep_merge(merged, inc_data)
+
+    # Then deep-merge current file's own keys on top
+    merged = _deep_merge(merged, data)
+
+    return merged
+
+
+class Config:
+    """Resolved handoff configuration.
+
+    Mechanism (backend_types.yaml) + Data (~/.handoff/config.yaml).
+    The two layers are loaded independently; user config CANNOT override the
+    mechanism layer (flags, PTY).  Backend resolution deep-merges the
+    mechanism fields for the backend's type with the user's backend fields.
+    """
+
+    def __init__(self):
+        _ensure_user_config_exists()
+
+        # Mechanism layer — how each type is launched (NOT overridable).
+        self._backend_types = _load_yaml(_BACKEND_TYPES_PATH)
+        types = self._backend_types.get("types")
+        if not isinstance(types, dict) or not types:
+            print(
+                f"handoff: missing or invalid types in {_BACKEND_TYPES_PATH}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        # Data layer — user's backends (sole source of backend definitions).
+        self._user = _load_with_includes(user_config_path())
+        self._warn_deprecated()
+        self._validate()
+
+    # ── public read-only helpers ──────────────────────────────────────────────
+
+    @property
+    def user_config_path(self) -> str:
+        return user_config_path()
+
+    @property
+    def backend_types_path(self) -> str:
+        return _BACKEND_TYPES_PATH
+
+    @property
+    def default_backend(self) -> str:
+        """The default backend: first entry in the user config (insertion order)."""
+        backends = self._user.get("backends", {})
+        if isinstance(backends, dict) and backends:
+            return next(iter(backends))
+        print("handoff: no backends configured", file=sys.stderr)
+        sys.exit(1)
+
+    @property
+    def system_prompt(self) -> str:
+        """User's system_prompt if set, otherwise the built-in default."""
+        user_sp = self._user.get("system_prompt")
+        if user_sp is not None:
+            return user_sp
+        return self._backend_types.get("system_prompt", "")
+
+    @property
+    def type_defaults(self) -> dict:
+        """Mechanism-layer type definitions (command, pty, flags). Read-only."""
+        return copy.deepcopy(self._backend_types.get("types", {}))
+
+    @property
+    def backends(self) -> dict:
+        """Return the resolved backends dict.
+
+        Resolution per backend: types[<type>] mechanism fields -> backend's own
+        fields from user config (deep merge; lists replaced wholesale). String
+        values get ${ENV_VAR} interpolation.
+
+        Every resolved backend carries a `type` key (defaults to "claude" when
+        omitted).
+        """
+        raw = self._user.get("backends", {})
+        if not isinstance(raw, dict):
+            print("handoff: config key 'backends' must be a mapping", file=sys.stderr)
+            sys.exit(1)
+
+        types = self._backend_types.get("types", {}) or {}
+        result = {}
+        for name, overrides in raw.items():
+            if not isinstance(overrides, dict):
+                print(f"handoff: backend '{name}' must be a mapping", file=sys.stderr)
+                sys.exit(1)
+            btype = overrides.get("type", "claude")
+            base = types.get(btype)
+            if not isinstance(base, dict):
+                base = {}
+            merged = _deep_merge(base, overrides)
+            merged["type"] = btype
+            result[name] = _expand_env_vars(merged)
+        return result
+
+    def get_backend(self, name: str) -> Optional[dict]:
+        """Resolve a named backend (returns deep-copied merged dict or None)."""
+        backends = self.backends  # already merged with type mechanism
+        return copy.deepcopy(backends.get(name))
+
+    def get_config_paths(self) -> list[str]:
+        """Return paths of all config source files (for mtime checks)."""
+        paths = [_BACKEND_TYPES_PATH]
+        uc = user_config_path()
+        if os.path.isfile(uc):
+            paths.append(uc)
+        return paths
+
+    # ── validation ────────────────────────────────────────────────────────────
+
+    def _warn_deprecated(self):
+        """Warn about (and drop) top-level keys that belong to the mechanism
+        layer or are otherwise removed.  system_prompt is deliberately kept —
+        users can override it.
+        """
+        for key in _DEPRECATED_KEYS:
+            if key in self._user:
+                print(
+                    f"handoff: config key '{key}' is deprecated and was ignored "
+                    f"(the mechanism layer is now in backend_types.yaml; "
+                    f"backends carry their own model/pro_model fields)",
+                    file=sys.stderr,
+                )
+                self._user.pop(key, None)
+
+    def _validate(self):
+        backends = self._user.get("backends", {})
+        if not isinstance(backends, dict) or not backends:
+            print(
+                "handoff: no backends configured. "
+                f"See {_TEMPLATE_URL} for the default template.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        types = self._backend_types.get("types", {})
+        known_types = list(types.keys()) if isinstance(types, dict) else []
+
+        for name, overrides in backends.items():
+            if not isinstance(overrides, dict):
+                continue  # reported when resolving
+            btype = overrides.get("type", "claude")
+            if btype not in types:
+                print(
+                    f"handoff: backend '{name}' has unknown type '{btype}' "
+                    f"(known: {', '.join(sorted(known_types))})",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            if btype == "claude" and not overrides.get("model"):
+                print(
+                    f"handoff: backend '{name}' (type claude) must have a 'model' field. "
+                    f"See {_TEMPLATE_URL} for the default template.",
+                    file=sys.stderr,
+                )
+                sys.exit(1)

cli/core.py

@@ -0,0 +1,302 @@
+"""Core shared utilities for handoff.
+
+Includes seq_code arithmetic, database operations, formatting helpers,
+automatic migration from the legacy state directory, and shared constants.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import sqlite3
+import uuid as _uuid
+import datetime
+import re
+from typing import Optional
+
+STATE_DIR = os.path.expanduser("~/.handoff")
+_LEGACY_DIR = os.path.expanduser("~/.ds-cli")  # pre-rename state dir, used only for migration
+DB_DIR = os.path.join(STATE_DIR, "runs")
+DB_PATH = os.path.join(DB_DIR, "handoff.db")
+_LEGACY_DB = os.path.join(DB_DIR, "dscli.db")  # pre-rename DB name, used only for migration
+TASKS_DIR = os.path.join(STATE_DIR, "tasks")
+_MAX_DAILY = 1035  # ZZ is max seq_code
+
+UUID_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+
+
+# ── migration ──────────────────────────────────────────────────────────────────
+
+
+def _migrate_legacy_state():
+    """If the legacy state dir exists and ~/.handoff does not, rename the entire directory.
+
+    Also migrates the SQLite database file and any WAL/SHM sidecars from
+    the old name to handoff.db inside the renamed directory.
+    """
+    if not os.path.isdir(_LEGACY_DIR):
+        return
+    if os.path.isdir(STATE_DIR):
+        return
+
+    print(f"handoff: detected legacy {_LEGACY_DIR}, migrating to {STATE_DIR} ...", file=sys.stderr)
+    try:
+        os.rename(_LEGACY_DIR, STATE_DIR)
+    except OSError as e:
+        print(f"handoff: migration rename failed: {e}", file=sys.stderr)
+        return
+
+    # Rename main DB file
+    if os.path.isfile(_LEGACY_DB) and not os.path.isfile(DB_PATH):
+        os.rename(_LEGACY_DB, DB_PATH)
+        # Also move WAL/SHM sidecars
+        for suffix in ("-wal", "-shm"):
+            old_sidecar = _LEGACY_DB + suffix
+            if os.path.isfile(old_sidecar):
+                try:
+                    os.rename(old_sidecar, DB_PATH + suffix)
+                except OSError:
+                    pass
+
+    print("handoff: migration complete.", file=sys.stderr)
+
+
+# ── seq_code helpers ──────────────────────────────────────────────────────────
+
+
+def counter_to_seq_code(n: int) -> str:
+    """Convert 1-based daily counter to 2-char seq_code.
+
+    1..99  → "01".."99"
+    100+   → A0, A1..A9, AA..AZ, B0..ZZ
+    Raises ValueError if n exceeds ZZ (1035).
+    """
+    if n < 1:
+        raise ValueError(f"counter must be >= 1, got {n}")
+    if n <= 99:
+        return f"{n:02d}"
+    val = n - 100  # 0-based offset from start of letter encoding
+    if val >= 26 * 36:
+        raise ValueError(f"counter too large, max {_MAX_DAILY} (ZZ), got {n}")
+    first = chr(ord("A") + val // 36)
+    r = val % 36
+    second = chr(ord("0") + r) if r < 10 else chr(ord("A") + r - 10)
+    return first + second
+
+
+def seq_code_to_counter(code: str) -> int:
+    """Inverse of counter_to_seq_code: '01' → 1, 'A0' → 100, 'ZZ' → 1035."""
+    if len(code) != 2:
+        raise ValueError(f"invalid seq_code length: {code!r}")
+    if code.isdigit():
+        return int(code)
+    first, second = code[0], code[1]
+    if not ("A" <= first <= "Z"):
+        raise ValueError(f"invalid seq_code: {code!r}")
+    first_idx = ord(first) - ord("A")
+    if "0" <= second <= "9":
+        second_idx = ord(second) - ord("0")
+    elif "A" <= second <= "Z":
+        second_idx = ord(second) - ord("A") + 10
+    else:
+        raise ValueError(f"invalid seq_code char: {second!r}")
+    return 100 + first_idx * 36 + second_idx
+
+
+# ── database ──────────────────────────────────────────────────────────────────
+
+
+def get_db():
+    """Open (or create) the SQLite database, return a connection with row_factory set."""
+    _migrate_legacy_state()
+    os.makedirs(DB_DIR, exist_ok=True)
+    os.makedirs(TASKS_DIR, exist_ok=True)
+    conn = sqlite3.connect(DB_PATH)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS runs (
+            id          INTEGER PRIMARY KEY AUTOINCREMENT,
+            seq         INTEGER NOT NULL,
+            seq_code    TEXT NOT NULL,
+            run_id      TEXT NOT NULL UNIQUE,
+            run_day     TEXT NOT NULL,
+            uuid        TEXT NOT NULL UNIQUE,
+            session_id  TEXT,
+            cwd         TEXT NOT NULL,
+            prompt      TEXT NOT NULL,
+            jsonl_path  TEXT NOT NULL,
+            created_at  TEXT NOT NULL DEFAULT (datetime('now', 'localtime')),
+            status      TEXT DEFAULT 'running',
+            backend     TEXT DEFAULT ''
+        )
+    """)
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS run_counters (
+            day     TEXT PRIMARY KEY,
+            last_n  INTEGER NOT NULL
+        )
+    """)
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_runs_run_id   ON runs(run_id)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_runs_seq      ON runs(seq)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_runs_created  ON runs(created_at)")
+
+    # Recreate schema if old table is missing new columns (e.g. reset not run)
+    try:
+        cursor = conn.execute("PRAGMA table_info(runs)")
+        cols = {row[1] for row in cursor.fetchall()}
+        # In-place migration: add session_id and backfill from uuid for old rows.
+        if "session_id" not in cols:
+            conn.execute("ALTER TABLE runs ADD COLUMN session_id TEXT")
+            conn.execute(
+                "UPDATE runs SET session_id = uuid WHERE session_id IS NULL OR session_id = ''"
+            )
+            cols.add("session_id")
+        missing = {"run_id", "seq_code", "run_day", "backend"} - cols
+        if missing:
+            print(
+                f"handoff: schema missing columns {missing}; "
+                f"delete ~/.handoff/runs/handoff.db and retry",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+    except sqlite3.Error:
+        pass
+
+    conn.commit()
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def create_run(
+    conn: sqlite3.Connection,
+    cwd: str,
+    prompt_text: str,
+    backend_name: str = "",
+    session_id: Optional[str] = None,
+):
+    """Allocate a new run inside a BEGIN IMMEDIATE transaction.
+
+    Assigns daily counter, seq_code, run_id, uuid, jsonl_path.
+    Records the backend name used.
+
+    `session_id` is the underlying claude session to associate this run with.
+    For a fresh run it is None and defaults to the row's own uuid. For a
+    `resume` continuation it is the parent conversation's session_id, so the new
+    row (new run_id/seq/files) shares one claude session across turns.
+
+    Returns (run_id, uuid, jsonl_path).  Caller must commit/rollback.
+    """
+    conn.execute("BEGIN IMMEDIATE")
+    today = datetime.date.today()
+    today_iso = today.isoformat()
+    mmdd = today.strftime("%m%d")
+
+    row = conn.execute(
+        "SELECT last_n FROM run_counters WHERE day = ?", (today_iso,)
+    ).fetchone()
+    n = (row[0] + 1) if row else 1
+
+    if n > _MAX_DAILY:
+        conn.execute("ROLLBACK")
+        print("handoff: exceeded maximum daily run count (ZZ = 1035)", file=sys.stderr)
+        sys.exit(2)
+
+    conn.execute(
+        "INSERT OR REPLACE INTO run_counters (day, last_n) VALUES (?, ?)",
+        (today_iso, n),
+    )
+
+    seq_code = counter_to_seq_code(n)
+    run_id = f"hd-{mmdd}-{seq_code}"
+    uid = str(_uuid.uuid4()).lower()
+    sess = session_id or uid
+    jsonl_path = os.path.join(DB_DIR, f"{run_id}-{uid}.jsonl")
+
+    conn.execute(
+        "INSERT INTO runs (seq, seq_code, run_id, run_day, uuid, session_id, cwd, prompt, jsonl_path, backend) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        (n, seq_code, run_id, today_iso, uid, sess, cwd, prompt_text, jsonl_path, backend_name),
+    )
+    return run_id, uid, jsonl_path
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+
+def short_path(p):
+    """Collapse $HOME to ~/."""
+    home = os.path.expanduser("~")
+    if p.startswith(home + "/"):
+        return "~/" + p[len(home) + 1:]
+    if p == home:
+        return "~"
+    return p
+
+
+def prompt_prefix(prompt: Optional[str], width: int = 30) -> str:
+    lines = [l for l in (prompt or "").splitlines() if l.strip()]
+    first = lines[0].strip() if lines else ""
+    return first[:width]
+
+
+def format_run_row(row, full_cwd: bool = False) -> dict[str, str]:
+    try:
+        dt = datetime.datetime.strptime(row["created_at"], "%Y-%m-%d %H:%M:%S")
+        if dt.date() == datetime.date.today():
+            date_str = dt.strftime("%H:%M")
+        else:
+            date_str = dt.strftime("%m-%d %H:%M")
+    except (ValueError, TypeError):
+        date_str = row["created_at"] or "?"
+
+    cwd = row["cwd"]
+    cwd_disp = short_path(cwd) if full_cwd else (os.path.basename(cwd) or cwd)
+    return {
+        "id": row["run_id"],
+        "date": date_str,
+        "prompt": prompt_prefix(row["prompt"], 40),
+        "cwd": cwd_disp,
+        "uuid": row["uuid"],
+        "status": row["status"],
+        "backend": row_value(row, "backend", "") or "",
+    }
+
+
+def row_value(row, key: str, default=None):
+    """Read key from sqlite3.Row/dict-like row without assuming dict.get()."""
+    try:
+        return row[key]
+    except (KeyError, IndexError, TypeError):
+        return default
+
+
+def find_run(conn: sqlite3.Connection, selector: Optional[str]):
+    """Find a run by run_id, numeric seq, or latest."""
+    if selector:
+        row = conn.execute(
+            "SELECT * FROM runs WHERE run_id = ?", (selector,)
+        ).fetchone()
+        if row:
+            return row
+        try:
+            seq = int(selector)
+        except ValueError:
+            return None
+        return conn.execute(
+            "SELECT * FROM runs WHERE seq = ? ORDER BY created_at DESC LIMIT 1",
+            (seq,),
+        ).fetchone()
+
+    return conn.execute("SELECT * FROM runs ORDER BY created_at DESC LIMIT 1").fetchone()
+
+
+def task_paths(run_id: str):
+    """Return (prompt, out, result) paths under TASKS_DIR using run_id as basename."""
+    os.makedirs(TASKS_DIR, exist_ok=True)
+    return (
+        os.path.join(TASKS_DIR, f"{run_id}.prompt.txt"),
+        os.path.join(TASKS_DIR, f"{run_id}.out.txt"),
+        os.path.join(TASKS_DIR, f"{run_id}.result.md"),
+    )