hubkit-cli 0.1.0__py3-none-any.whl

hubcore/__init__.py

@@ -0,0 +1 @@
+"""hubkit core: orders, status, watchdog, hooks. Stdlib only, Python 3.11+."""

hubcore/cli.py

@@ -0,0 +1,273 @@
+"""hubkit command line."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+import tomllib
+from pathlib import Path
+
+from . import compat, config, hooks, install, lessons, routed, status, store, watcher
+from .orders import Orders
+from .redact import count_hits_text
+
+
+def kv(pairs: list[str]) -> dict[str, str]:
+    """Parse repeated NAME=VALUE arguments into a dict."""
+    out = {}
+    for p in pairs or []:
+        k, _, v = p.partition("=")
+        out[k.strip()] = v.strip()
+    return out
+
+
+def cmd_order(a, cfg: dict) -> int:
+    """Run an `order` verb; exit 2 with a message on an unknown id or refused action."""
+    o = Orders(cfg)
+    act = a.action
+    try:
+        if act == "ls":
+            for x in o.live():
+                print(o.status_line(x))
+        elif act == "status":
+            items = [o.get(a.id)] if a.id else o.live()
+            for x in items:
+                print(o.status_line(x))
+        elif act == "open":
+            x = o.open(a.kind, a.quote, state="unconfirmed" if a.unconfirmed else "open")
+            print(o.status_line(x))
+        elif act == "confirm":
+            o.confirm(a.id)
+        elif act == "move":
+            msg = o.move(a.id, a.note, a.estimate)
+            if msg:
+                print(msg)
+        elif act == "block":
+            print(o.block(a.id, a.on, a.fix, a.holder))
+        elif act == "result":
+            o.result(a.id, a.note)
+        elif act == "hold":
+            o.hold(a.id, a.quote)
+        elif act == "resume":
+            o.resume(a.id)
+        elif act == "cancel":
+            o.cancel(a.id, a.quote)
+        elif act == "close":
+            print(o.close(a.id, kv(a.evidence)))
+        elif act == "metrics":
+            print(json.dumps(o.metrics(a.day or store.day_of(cfg, time.time()))))
+    except (KeyError, ValueError) as e:
+        print(f"error: {e.args[0] if e.args else e}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def cmd_work(a, cfg: dict) -> int:
+    """Run a `work` verb (add, done, ls)."""
+    try:
+        if a.action == "add" and a.kind == "routed":
+            if not (a.owner and a.title):
+                raise ValueError("routed items need --owner and --title")
+            prs = routed.refs(cfg, " ".join(a.pr))
+            heads = {u: a.head for u in prs} if a.head else {}
+            print(routed.record(cfg, a.owner, a.title, prs, heads, review=routed.is_review(cfg, a.title + " " + " ".join(a.pr)), estimate=a.estimate)["id"])
+        elif a.action == "add":
+            print(status.work_add(cfg, a.kind, a.title, a.owner, a.note, a.estimate)["id"])
+        elif a.action == "block":
+            print(watcher.set_blocked(cfg, a.id, a.on))
+        elif a.action == "estimate":
+            from . import slow
+
+            print(slow.re_estimate(cfg, a.id, a.minutes or 0, a.why))
+        elif a.action == "done":
+            print(status.work_done(cfg, a.id, a.note))
+        else:
+            for i in status.work_load(store.state(cfg)):
+                print(f"{i['id']} [{i['kind']}] {i['title']}")
+    except (KeyError, ValueError) as e:
+        print(f"error: {e.args[0]}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def cron_configured() -> bool:
+    """True when the user's scheduler (crontab, or Task Scheduler on Windows) holds an active entry that runs hubkit."""
+    return any("hubkit" in x for x in compat.scheduler_lines())
+
+
+def cron_line(cfg: dict, sd: Path) -> str:
+    """The `cron:` doctor line. When cron is configured, a `seen/cron` older than `watchdog.cron_stale_min` (or
+    never written) is flagged: every tick run touches it first, so a stale one means cron is not running hubkit."""
+    f = sd / "seen" / "cron"
+    if not cron_configured():
+        return f"cron: no hubkit line in the {compat.scheduler_name()}"
+    age = (time.time() - f.stat().st_mtime) / 60 if f.exists() else None
+    if age is None or age > float(cfg["watchdog"]["cron_stale_min"]):
+        shown = "never ran" if age is None else f"last ran {int(age)} min ago"
+        return f"cron: STALE: a hubkit {compat.scheduler_name()} entry exists but {shown} (limit {cfg['watchdog']['cron_stale_min']} min); check cron's mail and that the line runs"
+    return "cron: ok"
+
+
+def intents_gaps(cfg: dict) -> list[str]:
+    """Sections and keys the shipped intents.example.toml has and the user's own intents.toml lacks (a new release adds checks the old file never turns on)."""
+    mine = config.intents_path(cfg)
+    example = config.SKILL_DIR / "intents.example.toml"
+    if mine == example or not mine.exists() or not example.exists():
+        return []
+    have, want = tomllib.loads(mine.read_text(encoding="utf-8")), tomllib.loads(example.read_text(encoding="utf-8"))
+    gaps = [f"[{sec}]" for sec in want if sec not in have]
+    gaps += [f"[{sec}] {key}" for sec in want if sec in have and sec != "kinds" for key in want[sec] if key not in have[sec]]
+    return gaps
+
+
+def cmd_doctor(a, cfg: dict) -> int:
+    """Print config, bind, hook heartbeat and state health; exit 1 on secret-shaped strings or private terms."""
+    sd = store.state(cfg)
+    problems = 0
+    print(f"config: {cfg['_config_path']} ({'found' if Path(cfg['_config_path']).exists() else 'defaults'})")
+    print(f"state: {sd}")
+    b = hooks.read_bind(cfg)
+    print(f"bind: {'live ' + str(b.get('name')) if hooks.bind_alive(b) else 'none or dead'}")
+    for name in ("session", "prompt", "answer", "routed", "stop", "tick", "cron"):
+        f = sd / "seen" / name
+        print(f"seen/{name}: {int((time.time() - f.stat().st_mtime) / 60)} min ago" if f.exists() else f"seen/{name}: never")
+    print(cron_line(cfg, sd))
+    rows, bad = store.read_rows(sd / "orders.jsonl")
+    print(f"orders.jsonl: {len(rows)} rows, {bad} bad lines")
+    errs = store.read_rows(sd / "hook-errors.jsonl")[0]
+    print(f"hook-errors.jsonl: {len(errs)} rows")
+    gaps = intents_gaps(cfg)
+    if gaps:
+        print(f"WARNING intents.toml lacks what intents.example.toml has: {', '.join(gaps)}. Copy those lines from the example; the checks they configure use built-in defaults or stay off.")
+    print(f"transcript scan: {status.hook_errors(cfg)}")
+    hits = sum(count_hits_text(p.read_text(encoding="utf-8", errors="replace")) for p in sd.rglob("*.jsonl"))
+    print(f"secret-shaped strings in state (count only): {hits}")
+    problems += hits
+    if a.check_clean:
+        terms = [t.lower() for t in cfg["private"]["terms"]]
+        dirty = []
+        for p in config.SKILL_DIR.rglob("*"):
+            if p.is_file() and not {"__pycache__", ".pytest_cache", ".git", ".ruff_cache", ".mypy_cache"} & set(p.relative_to(config.SKILL_DIR).parts) \
+                    and p.suffix in (".py", ".md", ".toml", ".txt", ".yml", ".yaml", ".gitignore", ""):
+                low = p.read_text(encoding="utf-8", errors="replace").lower()
+                dirty += [str(p.relative_to(config.SKILL_DIR)) for t in terms if t and t in low]
+        print(f"private terms in skill files (names only, no matches shown): {sorted(set(dirty)) or 'none'} [{len(terms)} terms]")
+        problems += len(dirty)
+    return 1 if problems else 0
+
+
+def run() -> None:
+    """Console-script entry point (`uv tool install hubkit-cli`)."""
+    sys.exit(main())
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse argv and dispatch one verb. Returns the process exit code."""
+    compat.utf8_stdio()
+    p = argparse.ArgumentParser(prog="hubkit")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    h = sub.add_parser("hook")
+    h.add_argument("event", choices=sorted(hooks.HOOKS))
+
+    b = sub.add_parser("bind")
+    b.add_argument("--pid", type=int)
+    sub.add_parser("unbind")
+
+    sk = sub.add_parser("skills")
+    sk.add_argument("--install", metavar="DIR", required=True, help="the skills directory of your agent tool, for example ~/.claude/skills")
+
+    hk = sub.add_parser("hooks")
+    hk.add_argument("--skills-dir", default="$HOME/.claude/skills")
+    hk.add_argument("--merge-guard", action="store_true", help="include the warn-only PreToolUse merge check")
+
+    k = sub.add_parser("asks")
+    k.add_argument("action", choices=["ls"])
+    k.add_argument("--since", default="12h", help="how far back, for example 30m, 12h, 2d")
+
+    o = sub.add_parser("order")
+    o.add_argument("action", choices=["ls", "status", "open", "confirm", "move", "block", "result", "hold", "resume", "cancel", "close", "metrics"])
+    o.add_argument("id", nargs="?")
+    o.add_argument("--kind")
+    o.add_argument("--quote", default="")
+    o.add_argument("--note", default="")
+    o.add_argument("--on", default="", help="block: what the order is blocked on")
+    o.add_argument("--fix", default="", help="block: the action running now to clear it")
+    o.add_argument("--holder", default="", help="block: who runs the fix")
+    o.add_argument("--evidence", action="append", default=[], help="name=value (value 'file:<path>' is checked)")
+    o.add_argument("--day")
+    o.add_argument("--unconfirmed", action="store_true")
+    o.add_argument("--estimate", type=int, help="move: minutes this order should take (default: the usual time)")
+
+    w = sub.add_parser("work")
+    w.add_argument("action", choices=["add", "done", "ls", "estimate", "block"])
+    w.add_argument("id", nargs="?")
+    w.add_argument("--kind", default="active")
+    w.add_argument("--title", default="")
+    w.add_argument("--owner", default="")
+    w.add_argument("--note", default="")
+    w.add_argument("--pr", action="append", default=[], help="routed: PR URL (repeatable)")
+    w.add_argument("--estimate", type=int, help="minutes this job should take")
+    w.add_argument("--minutes", type=int, help="estimate: the new total minutes")
+    w.add_argument("--on", default="", help="block: the job this one waits on (empty clears)")
+    w.add_argument("--why", default="", help="estimate: the reason for the new estimate")
+    w.add_argument("--head", default="", help="routed: head sha the work was routed at")
+
+    t = sub.add_parser("tick")
+    t.add_argument("--no-notify", action="store_true")
+    t.add_argument("--if-bound", action="store_true", help="no-op unless a hub is bound or orders are open (for cron)")
+    wt = sub.add_parser("watch")
+    wt.add_argument("--interval", type=float, default=300)
+    wt.add_argument("--max-cycles", type=int, default=12)
+
+    st = sub.add_parser("status")
+    st.add_argument("--json", action="store_true")
+    e = sub.add_parser("eod")
+    e.add_argument("--day")
+    e.add_argument("--note", default="")
+
+    d = sub.add_parser("doctor")
+    d.add_argument("--check-clean", action="store_true")
+
+    a = p.parse_args(argv)
+    if a.cmd == "hook":
+        return hooks.main(a.event)
+    cfg = config.load()
+    try:
+        if a.cmd == "bind":
+            print(hooks.bind(cfg, a.pid))
+        elif a.cmd == "unbind":
+            print(hooks.unbind(cfg))
+        elif a.cmd == "order":
+            return cmd_order(a, cfg)
+        elif a.cmd == "work":
+            return cmd_work(a, cfg)
+        elif a.cmd == "tick":
+            store.touch_seen(store.state(cfg), "cron")
+            if a.if_bound and not (hooks.bind_alive(hooks.read_bind(cfg)) or watcher.live_jobs(cfg, Orders(cfg))):
+                return 0
+            for x in status.tick(cfg, notify=not a.no_notify):
+                print("ALERT " + x["msg"])
+        elif a.cmd == "skills":
+            print("\n".join(install.install_skills(Path(a.install).expanduser())))
+        elif a.cmd == "hooks":
+            print(install.hooks_block(a.skills_dir, a.merge_guard))
+        elif a.cmd == "asks":
+            print("\n".join(lessons.asks_lines(cfg, a.since)))
+        elif a.cmd == "watch":
+            return status.watch(cfg, a.interval, a.max_cycles)
+        elif a.cmd == "status":
+            st_ = status.write_status(cfg)
+            print(json.dumps(st_, indent=1) if a.json else status.render_block(cfg, Orders(cfg), st_))
+        elif a.cmd == "eod":
+            day = a.day or store.day_of(cfg, time.time())
+            out = status.eod(cfg, day, a.note)
+            print(out.read_text(encoding="utf-8"), end="")
+        elif a.cmd == "doctor":
+            return cmd_doctor(a, cfg)
+    except (RuntimeError, ValueError, store.StateError) as err:
+        print(f"error: {err}", file=sys.stderr)
+        return 2
+    return 0

hubcore/compat.py

@@ -0,0 +1,187 @@
+"""The one place that knows which operating system it runs on (stdlib only).
+
+Linux reads /proc; macOS and other POSIX systems ask `ps`; Windows asks kernel32 through ctypes. File locks are
+flock on POSIX and msvcrt on Windows. The scheduler check is crontab on POSIX and Task Scheduler on Windows.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+_PROC = Path("/proc/self/stat")
+
+
+# ---- process identity: (pid, start time) names one process for as long as it lives ----
+
+
+def _ps(*args: str) -> str | None:
+    """Output of `ps` (POSIX without /proc, e.g. macOS) or None when it fails or prints nothing."""
+    try:
+        r = subprocess.run(["ps", *args], capture_output=True, encoding="utf-8", errors="replace", timeout=5, check=False, env={**os.environ, "LC_ALL": "C"})
+    except OSError, subprocess.SubprocessError:
+        return None
+    out = r.stdout.strip()
+    return out if r.returncode == 0 and out else None
+
+
+def _win_creation_time(pid: int) -> str | None:
+    if sys.platform != "win32":
+        raise OSError("Windows only")
+    import ctypes
+    from ctypes import wintypes
+
+    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    k32.OpenProcess.restype = wintypes.HANDLE
+    k32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    k32.GetProcessTimes.argtypes = [wintypes.HANDLE, *([ctypes.POINTER(wintypes.FILETIME)] * 4)]
+    k32.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+    k32.CloseHandle.argtypes = [wintypes.HANDLE]
+    handle = k32.OpenProcess(0x1000 | 0x100000, False, pid)  # QUERY_LIMITED_INFORMATION | SYNCHRONIZE
+    if not handle:
+        return None
+    try:
+        created, exited, kernel, user = (wintypes.FILETIME() for _ in range(4))
+        if not k32.GetProcessTimes(handle, *(ctypes.byref(t) for t in (created, exited, kernel, user))):
+            return None
+        if k32.WaitForSingleObject(handle, 0) == 0:  # signalled: the process has ended
+            return None
+        return str((created.dwHighDateTime << 32) | created.dwLowDateTime)
+    finally:
+        k32.CloseHandle(handle)
+
+
+def proc_start(pid: int) -> str | None:
+    """An opaque start-time token for a live process, or None when it is gone. Equal tokens mean the same process."""
+    if sys.platform == "win32":
+        return _win_creation_time(pid)
+    if _PROC.exists():
+        try:
+            return Path(f"/proc/{pid}/stat").read_text(encoding="utf-8").rsplit(")", 1)[1].split()[19]
+        except (OSError, IndexError):
+            return None
+    return _ps("-o", "lstart=", "-p", str(pid))
+
+
+def _win_parent(pid: int) -> int | None:
+    if sys.platform != "win32":
+        raise OSError("Windows only")
+    import ctypes
+    from ctypes import wintypes
+
+    class Entry(ctypes.Structure):
+        _fields_ = [
+            ("dwSize", wintypes.DWORD),
+            ("cntUsage", wintypes.DWORD),
+            ("th32ProcessID", wintypes.DWORD),
+            ("th32DefaultHeapID", ctypes.c_void_p),
+            ("th32ModuleID", wintypes.DWORD),
+            ("cntThreads", wintypes.DWORD),
+            ("th32ParentProcessID", wintypes.DWORD),
+            ("pcPriClassBase", ctypes.c_long),
+            ("dwFlags", wintypes.DWORD),
+            ("szExeFile", ctypes.c_char * 260),
+        ]
+
+    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    k32.CreateToolhelp32Snapshot.restype = wintypes.HANDLE
+    k32.CreateToolhelp32Snapshot.argtypes = [wintypes.DWORD, wintypes.DWORD]
+    k32.Process32First.argtypes = k32.Process32Next.argtypes = [wintypes.HANDLE, ctypes.POINTER(Entry)]
+    k32.CloseHandle.argtypes = [wintypes.HANDLE]
+    snap = k32.CreateToolhelp32Snapshot(0x2, 0)  # TH32CS_SNAPPROCESS
+    if snap in (None, wintypes.HANDLE(-1).value):
+        return None
+    try:
+        entry = Entry()
+        entry.dwSize = ctypes.sizeof(Entry)
+        ok = k32.Process32First(snap, ctypes.byref(entry))
+        while ok:
+            if entry.th32ProcessID == pid:
+                return int(entry.th32ParentProcessID)
+            ok = k32.Process32Next(snap, ctypes.byref(entry))
+        return None
+    finally:
+        k32.CloseHandle(snap)
+
+
+def parent_pid(pid: int) -> int | None:
+    """Parent of a process, or None when unknown."""
+    if sys.platform == "win32":
+        return _win_parent(pid)
+    if _PROC.exists():
+        try:
+            return int(Path(f"/proc/{pid}/stat").read_text(encoding="utf-8").rsplit(")", 1)[1].split()[1])
+        except (OSError, IndexError, ValueError):
+            return None
+    out = _ps("-o", "ppid=", "-p", str(pid))
+    return int(out) if out and out.isdigit() else None
+
+
+# ---- file lock: held until the descriptor is closed ----
+
+
+def lock_exclusive(fd: int, wait: bool) -> bool:
+    """Take an exclusive lock on an open file. With wait, blocks until held; without, returns False when it is taken."""
+    if sys.platform == "win32":
+        import msvcrt
+
+        while True:
+            try:
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                return True
+            except OSError:
+                if not wait:
+                    return False
+                time.sleep(0.05)
+    import fcntl
+
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | (0 if wait else fcntl.LOCK_NB))
+        return True
+    except BlockingIOError:
+        return False
+
+
+def unlock(fd: int) -> None:
+    """Release a lock taken with lock_exclusive."""
+    if sys.platform == "win32":
+        import msvcrt
+
+        os.lseek(fd, 0, os.SEEK_SET)
+        msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+        return
+    import fcntl
+
+    fcntl.flock(fd, fcntl.LOCK_UN)
+
+
+# ---- the user's scheduler ----
+
+
+def scheduler_name() -> str:
+    return "Task Scheduler" if sys.platform == "win32" else "crontab"
+
+
+def scheduler_lines() -> list[str]:
+    """Active scheduled entries as text lines (crontab lines, or Task Scheduler rows). Unreadable counts as none."""
+    argv = ["schtasks", "/query", "/fo", "csv", "/nh"] if sys.platform == "win32" else ["crontab", "-l"]
+    try:
+        out = subprocess.run(argv, capture_output=True, encoding="utf-8", errors="replace", timeout=10, check=False).stdout
+    except OSError, subprocess.SubprocessError:
+        return []
+    return [x for x in out.splitlines() if not x.lstrip().startswith("#")]
+
+
+# ---- text I/O ----
+
+
+def utf8_stdio() -> None:
+    """Hooks exchange UTF-8 JSON; on Windows the default console code page would mangle it."""
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        reconf = getattr(stream, "reconfigure", None)
+        if reconf:
+            reconf(encoding="utf-8", errors="replace")

hubcore/config.py

@@ -0,0 +1,107 @@
+"""Config loading. All user-specific values come from one TOML file.
+
+Search order: $HUBKIT_CONFIG, $XDG_CONFIG_HOME/hubkit/config.toml, ~/.config/hubkit/config.toml.
+Missing file means built-in defaults (generic, nothing personal).
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+# A clone or an installed skill directory sits two levels above hubcore; the wheel carries the same tree as package data.
+SKILL_DIR = _HERE / "data" / "hub" if (_HERE / "data" / "hub").is_dir() else _HERE.parent.parent
+ENV_PREFIX = "HUBKIT"
+
+DEFAULTS: dict = {
+    "user": {"name": "the user", "timezone": "", "github_login": ""},
+    "hub": {"name": "hub"},
+    "paths": {
+        "state_dir": "",  # default: $XDG_STATE_HOME/hubkit
+        "intents": "",  # default: <config dir>/intents.toml, else skill example
+        "overlay": "",  # default: <config dir>/overlay.md
+        "learnings": "",  # default: <state dir>/learnings.md
+        "sessions_dir": "~/.claude/sessions",
+        "transcripts_glob": "~/.claude/projects/*/*.jsonl",
+        "extensions_dir": "",  # default: <config dir>/ext
+    },
+    "tools": {"mep": "mep", "notify_cmd": "", "gh": "gh"},
+    "routed": {"stall_min": 15, "min_chars": 200, "skip_owners": ["inbox"], "gh_timeout_s": 10,
+               "repo": "", "reply_window_min": 60, "queued_wait_min": 60, "owner_logins": {}, "skip_briefs": ["mep watch", "inbox watch"],
+        "activity_globs": [
+            "~/.claude/projects/*/*/subagents/agent-{id}.jsonl",
+            "/tmp/claude-*/*/*/tasks/{id}.output",
+        ], "reviewer_logins": [], "review_words": ["review"], "review_stall_min": 5, "review_overdue_min": 10},
+    "slow": {"min_samples": 3, "order_default_min": 30, "floor_min": 2, "tool_min": 2, "scan_kb": 2048},
+    "watcher": {"stale_agent_min": 30, "stuck_min": 30, "unhandled_min": 10, "waiting_min": 3, "active_s": 120, "watch_grace_min": 5, "notify_user": True},
+    "mep": {"enabled": True, "timeout_s": 30},
+    "watchdog": {"transcript_scan_hours": 24, "cron_stale_min": 15},
+    "think": {"decisions": ""},  # path of the active slug's decisions.md; its last lines go in the status block
+    "stop_guard": {"phrases": ["waits for your go", "say go", "want me to", "shall i"]},
+    "private": {"terms": []},
+}
+
+
+def config_dir() -> Path:
+    """Directory holding the user's config files ($XDG_CONFIG_HOME/hubkit)."""
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "hubkit"
+
+
+def config_path() -> Path:
+    """Path of config.toml: $HUBKIT_CONFIG, else <config dir>/config.toml."""
+    env = os.environ.get(f"{ENV_PREFIX}_CONFIG")
+    return Path(env).expanduser() if env else config_dir() / "config.toml"
+
+
+def _merge(base: dict, over: dict) -> dict:
+    out = dict(base)
+    for key, val in over.items():
+        if isinstance(val, dict) and isinstance(out.get(key), dict):
+            out[key] = _merge(out[key], val)
+        else:
+            out[key] = val
+    return out
+
+
+def load() -> dict:
+    """Defaults merged with the user's config.toml (a missing file means defaults)."""
+    path = config_path()
+    user: dict = {}
+    if path.exists():
+        user = tomllib.loads(path.read_text(encoding="utf-8"))
+    cfg = _merge(DEFAULTS, user)
+    cfg["_config_path"] = str(path)
+    cfg["_config_dir"] = str(path.parent)
+    return cfg
+
+
+def state_dir(cfg: dict) -> Path:
+    """State directory: $HUBKIT_STATE, else paths.state_dir, else $XDG_STATE_HOME/hubkit."""
+    env = os.environ.get(f"{ENV_PREFIX}_STATE")
+    if env:
+        return Path(env).expanduser()
+    if cfg["paths"]["state_dir"]:
+        return Path(cfg["paths"]["state_dir"]).expanduser()
+    base = os.environ.get("XDG_STATE_HOME") or str(Path.home() / ".local" / "state")
+    return Path(base) / "hubkit"
+
+
+def path_of(cfg: dict, key: str, default: Path) -> Path:
+    """A path from [paths] with ~ expanded, or `default` when unset."""
+    val = cfg["paths"].get(key, "")
+    return Path(val).expanduser() if val else default
+
+
+def sessions_dir(cfg: dict) -> Path:
+    """Where Claude Code writes one JSON file per running session."""
+    env = os.environ.get(f"{ENV_PREFIX}_SESSIONS")
+    return Path(env).expanduser() if env else Path(cfg["paths"]["sessions_dir"]).expanduser()
+
+
+def intents_path(cfg: dict) -> Path:
+    """The user's intents.toml, else the intents.example.toml shipped with the skill."""
+    mine = path_of(cfg, "intents", Path(cfg["_config_dir"]) / "intents.toml")
+    return mine if mine.exists() else SKILL_DIR / "intents.example.toml"