corrkit 0.5.0__py3-none-any.whl

accounts.py

@@ -0,0 +1,317 @@
+"""Account configuration — parse accounts.toml with provider presets."""
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+import msgspec
+
+CONFIG_PATH = Path("accounts.toml")
+
+PROVIDER_PRESETS: dict[str, dict[str, object]] = {
+    "gmail": {
+        "imap_host": "imap.gmail.com",
+        "imap_port": 993,
+        "imap_starttls": False,
+        "smtp_host": "smtp.gmail.com",
+        "smtp_port": 465,
+        "drafts_folder": "[Gmail]/Drafts",
+    },
+    "protonmail-bridge": {
+        "imap_host": "127.0.0.1",
+        "imap_port": 1143,
+        "imap_starttls": True,
+        "smtp_host": "127.0.0.1",
+        "smtp_port": 1025,
+        "drafts_folder": "Drafts",
+    },
+}
+
+
+_NON_ACCOUNT_KEYS = frozenset({"watch", "owner"})
+
+
+class OwnerConfig(msgspec.Struct):
+    github_user: str
+    name: str = ""
+
+
+class WatchConfig(msgspec.Struct):
+    poll_interval: int = 300
+    notify: bool = False
+
+
+class Account(msgspec.Struct):
+    provider: str = "imap"
+    user: str = ""
+    password: str = ""
+    password_cmd: str = ""
+    labels: list[str] = []
+    imap_host: str = ""
+    imap_port: int = 993
+    imap_starttls: bool = False
+    smtp_host: str = ""
+    smtp_port: int = 465
+    drafts_folder: str = "Drafts"
+    sync_days: int = 3650
+    default: bool = False
+
+
+def _apply_preset(account: Account) -> Account:
+    """Merge provider preset defaults — account values win over preset."""
+    preset = PROVIDER_PRESETS.get(account.provider)
+    if preset is None:
+        return account
+    # Only apply preset values for fields still at their Struct defaults
+    defaults = Account()
+    updates: dict[str, object] = {}
+    for key, preset_val in preset.items():
+        if getattr(account, key) == getattr(defaults, key):
+            updates[key] = preset_val
+    if updates:
+        return msgspec.structs.replace(account, **updates)
+    return account
+
+
+def resolve_password(account: Account) -> str:
+    """Return password: inline value if set, else run password_cmd."""
+    if account.password:
+        return account.password
+    if account.password_cmd:
+        result = subprocess.run(
+            account.password_cmd,
+            shell=True,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    raise ValueError(f"Account {account.user!r} has no password or password_cmd")
+
+
+def load_accounts(path: Path | None = None) -> dict[str, Account]:
+    """Parse accounts.toml → {name: Account} mapping."""
+    if path is None:
+        path = CONFIG_PATH
+    if not path.exists():
+        return {}
+    with open(path, "rb") as f:
+        raw = tomllib.load(f)
+    accounts_section = raw.get("accounts", raw)
+    result: dict[str, Account] = {}
+    for name, data in accounts_section.items():
+        if name in _NON_ACCOUNT_KEYS:
+            continue
+        account = msgspec.convert(data, Account)
+        account = _apply_preset(account)
+        result[name] = account
+    return result
+
+
+def _legacy_account_from_env() -> Account:
+    """Build a synthetic Account from legacy .env GMAIL_* vars."""
+    from dotenv import load_dotenv
+
+    load_dotenv()
+
+    user = os.environ.get("GMAIL_USER_EMAIL", "")
+    password = os.environ.get("GMAIL_APP_PASSWORD", "")
+    labels_str = os.environ.get("GMAIL_SYNC_LABELS", "")
+    sync_days = int(os.environ.get("GMAIL_SYNC_DAYS", "3650"))
+
+    if not user:
+        raise SystemExit("No accounts.toml found and GMAIL_USER_EMAIL not set in .env")
+
+    return Account(
+        provider="gmail",
+        user=user,
+        password=password.replace(" ", ""),
+        labels=[s.strip() for s in labels_str.split(",") if s.strip()],
+        imap_host="imap.gmail.com",
+        imap_port=993,
+        smtp_host="smtp.gmail.com",
+        smtp_port=465,
+        drafts_folder="[Gmail]/Drafts",
+        sync_days=sync_days,
+        default=True,
+    )
+
+
+def load_accounts_or_env(path: Path | None = None) -> dict[str, Account]:
+    """Load accounts.toml, falling back to .env GMAIL_* vars."""
+    accounts = load_accounts(path)
+    if accounts:
+        return accounts
+    return {"_legacy": _legacy_account_from_env()}
+
+
+def load_owner(path: Path | None = None) -> OwnerConfig:
+    """Load [owner] section from accounts.toml."""
+    if path is None:
+        path = CONFIG_PATH
+    if not path.exists():
+        raise SystemExit(
+            f"accounts.toml not found at {path}.\n"
+            "Add an [owner] section with github_user."
+        )
+    with open(path, "rb") as f:
+        raw = tomllib.load(f)
+    owner_data = raw.get("owner")
+    if owner_data is None:
+        raise SystemExit(
+            "Missing [owner] section in accounts.toml.\n"
+            'Add: [owner]\ngithub_user = "your-github-username"'
+        )
+    return msgspec.convert(owner_data, OwnerConfig)
+
+
+def get_default_account(accounts: dict[str, Account]) -> tuple[str, Account]:
+    """Return (name, account) for the default account."""
+    for name, acct in accounts.items():
+        if acct.default:
+            return name, acct
+    # Fall back to first account
+    name = next(iter(accounts))
+    return name, accounts[name]
+
+
+def get_account_for_email(
+    accounts: dict[str, Account], email_addr: str
+) -> tuple[str, Account] | None:
+    """Lookup account by email address."""
+    email_lower = email_addr.lower()
+    for name, acct in accounts.items():
+        if acct.user.lower() == email_lower:
+            return name, acct
+    return None
+
+
+def add_label_to_account(
+    account_name: str,
+    label: str,
+    path: Path | None = None,
+) -> bool:
+    """Add a label to an account's labels list in accounts.toml.
+
+    Does a text-level edit to preserve comments and formatting.
+    Returns True if the label was added, False if already present.
+    """
+    if path is None:
+        path = CONFIG_PATH
+    if not path.exists():
+        print(
+            f"accounts.toml not found at {path}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Verify account exists and label isn't already there
+    accounts = load_accounts(path)
+    if account_name not in accounts:
+        print(
+            f"Unknown account: {account_name}\nAvailable: {', '.join(accounts.keys())}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    if label in accounts[account_name].labels:
+        return False
+
+    # Text-level edit: find the labels line for this account section
+    text = path.read_text(encoding="utf-8")
+
+    # Find the account section header
+    section_re = re.compile(
+        rf"^\[accounts\.{re.escape(account_name)}\]",
+        re.MULTILINE,
+    )
+    section_match = section_re.search(text)
+    if not section_match:
+        # Try flat format (no [accounts.] prefix)
+        section_re = re.compile(rf"^\[{re.escape(account_name)}\]", re.MULTILINE)
+        section_match = section_re.search(text)
+    if not section_match:
+        print(
+            f"Could not find [{account_name}] section in {path}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Find the labels = [...] line after the section header
+    labels_re = re.compile(
+        r"^(labels\s*=\s*\[)(.*?)(\])",
+        re.MULTILINE,
+    )
+    # Search from the section start
+    labels_match = labels_re.search(text, section_match.end())
+    if not labels_match:
+        print(
+            f"Could not find labels line for account {account_name}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Check it's within this section (before next section header)
+    next_section = re.search(r"^\[", text[section_match.end() :], re.MULTILINE)
+    beyond_section = (
+        next_section
+        and labels_match.start() > section_match.end() + next_section.start()
+    )
+    if beyond_section:
+        print(
+            f"Could not find labels line for account {account_name}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Append the label
+    existing = labels_match.group(2).strip()
+    if existing:
+        new_labels = f'{existing}, "{label}"'
+    else:
+        new_labels = f'"{label}"'
+
+    new_text = (
+        text[: labels_match.start()]
+        + f"labels = [{new_labels}]"
+        + text[labels_match.end() :]
+    )
+    path.write_text(new_text, encoding="utf-8")
+    return True
+
+
+def add_label_main() -> None:
+    """CLI: corrkit add-label LABEL --account ACCOUNT"""
+    parser = argparse.ArgumentParser(
+        description="Add a label to an account's sync config"
+    )
+    parser.add_argument("label", help="Label to add")
+    parser.add_argument(
+        "--account",
+        required=True,
+        help="Account name in accounts.toml",
+    )
+    args = parser.parse_args()
+
+    added = add_label_to_account(args.account, args.label)
+    if added:
+        print(f"Added '{args.label}' to account '{args.account}' in accounts.toml")
+    else:
+        print(f"Label '{args.label}' already in account '{args.account}'")
+
+
+def load_watch_config(path: Path | None = None) -> WatchConfig:
+    """Load [watch] section from accounts.toml. Returns defaults if missing."""
+    if path is None:
+        path = CONFIG_PATH
+    if not path.exists():
+        return WatchConfig()
+    with open(path, "rb") as f:
+        raw = tomllib.load(f)
+    watch_data = raw.get("watch")
+    if watch_data is None:
+        return WatchConfig()
+    return msgspec.convert(watch_data, WatchConfig)

audit_docs.py

@@ -0,0 +1,251 @@
+"""Audit instruction files against the codebase.
+
+Checks:
+- Referenced paths exist on disk (from project structure tree)
+- uv run scripts are registered or point to existing files
+- Type conventions (msgspec vs dataclasses)
+- Combined instruction file line budget
+- Staleness (docs older than source)
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import tomllib
+from pathlib import Path
+from typing import NamedTuple
+
+
+def _find_root() -> Path:
+    """Find the project root by walking up from CWD looking for pyproject.toml."""
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        if (parent / "pyproject.toml").exists():
+            return parent
+    print("Error: could not find pyproject.toml", file=sys.stderr)
+    sys.exit(2)
+
+
+ROOT = _find_root()
+LINE_BUDGET = 1000
+SKIP_PATHS = {".env"}  # Gitignored files expected to be absent
+TOOL_COMMANDS = {"ruff", "ty", "pytest", "poe"}  # External tools invoked via uv run
+
+
+class Issue(NamedTuple):
+    file: str
+    line: int
+    message: str
+
+
+def find_instruction_files() -> list[Path]:
+    patterns = ["AGENTS.md", "README.md", ".claude/**/SKILL.md", "src/**/AGENTS.md"]
+    found: set[Path] = set()
+    for p in patterns:
+        found.update(ROOT.glob(p))
+    return sorted(found)
+
+
+def load_scripts() -> dict[str, str]:
+    with open(ROOT / "pyproject.toml", "rb") as f:
+        data = tomllib.load(f)
+    return data.get("project", {}).get("scripts", {})
+
+
+# --- Extractors ---
+
+
+def extract_tree_paths(content: str) -> list[tuple[int, str]]:
+    """Parse file paths from the Project Structure tree block."""
+    results: list[tuple[int, str]] = []
+    lines = content.splitlines()
+    in_section = False
+    in_block = False
+    stack: list[tuple[int, str]] = []  # (indent, dirname_with_slash)
+
+    for i, line in enumerate(lines, 1):
+        if line.startswith("## Project Structure"):
+            in_section = True
+            continue
+        if in_section and not in_block:
+            if line.strip().startswith("```"):
+                in_block = True
+                continue
+            if line.startswith("## "):
+                break
+            continue
+        if not in_block:
+            continue
+        if line.strip().startswith("```"):
+            break
+
+        stripped = line.rstrip()
+        if not stripped.strip():
+            continue
+        indent = len(stripped) - len(stripped.lstrip())
+        name = stripped.strip().split("#")[0].strip()
+        if not name:
+            continue
+        # Strip symlink arrow notation (e.g. "correspondence -> ~/path")
+        # Treat as directory since it's a symlink to a directory
+        if " -> " in name:
+            name = name.split(" -> ")[0].strip() + "/"
+
+        # Pop deeper/equal entries from stack
+        while stack and stack[-1][0] >= indent:
+            stack.pop()
+
+        if name.endswith("/"):
+            stack.append((indent, name))
+        else:
+            parts = [d for _, d in stack] + [name]
+            full = "".join(parts)
+            if full.startswith("correspondence-kit/"):
+                full = full[len("correspondence-kit/") :]
+            results.append((i, full))
+
+    return results
+
+
+def extract_uv_commands(content: str) -> list[tuple[int, str]]:
+    """Extract targets from `uv run <target>` in all contexts."""
+    results: list[tuple[int, str]] = []
+    pat = re.compile(r"uv run ([\w./-]+)")
+    for i, line in enumerate(content.splitlines(), 1):
+        for m in pat.finditer(line):
+            results.append((i, m.group(1)))
+    return results
+
+
+# --- Checks ---
+
+
+def check_tree_paths(rel: str, content: str) -> list[Issue]:
+    issues: list[Issue] = []
+    for line_no, path in extract_tree_paths(content):
+        if re.search(r"\[.*?]", path):
+            continue
+        if path in SKIP_PATHS:
+            continue
+        if not (ROOT / path).exists():
+            issues.append(
+                Issue(rel, line_no, f"Referenced path does not exist: {path}")
+            )
+    return issues
+
+
+def check_scripts(rel: str, content: str, registered: dict[str, str]) -> list[Issue]:
+    issues: list[Issue] = []
+    for line_no, target in extract_uv_commands(content):
+        if "/" in target or target.endswith(".py"):
+            if not (ROOT / target).exists():
+                issues.append(
+                    Issue(rel, line_no, f"Script file does not exist: {target}")
+                )
+        elif target not in TOOL_COMMANDS and target not in registered:
+            issues.append(
+                Issue(
+                    rel, line_no, f"Script not registered in pyproject.toml: {target}"
+                )
+            )
+    return issues
+
+
+def check_type_conventions(rel: str, content: str) -> list[Issue]:
+    issues: list[Issue] = []
+    if "msgspec" not in content:
+        return issues
+    for py in sorted(ROOT.glob("src/**/*.py")):
+        if py.name == "audit_docs.py":
+            continue  # skip self — contains the check string as a literal
+        text = py.read_text()
+        if "from dataclasses import" in text or "import dataclasses" in text:
+            py_rel = py.relative_to(ROOT)
+            for i, line in enumerate(content.splitlines(), 1):
+                if "msgspec" in line and (
+                    "dataclass" in line.lower() or "struct" in line.lower()
+                ):
+                    issues.append(
+                        Issue(
+                            rel,
+                            i,
+                            f'Docs say "msgspec" but {py_rel} uses dataclasses',
+                        )
+                    )
+                    break
+            break  # one report per doc file is enough
+    return issues
+
+
+def check_line_budget(
+    files: list[Path],
+) -> tuple[list[Issue], dict[str, int], int]:
+    counts: dict[str, int] = {}
+    total = 0
+    for f in files:
+        n = len(f.read_text().splitlines())
+        counts[str(f.relative_to(ROOT))] = n
+        total += n
+    issues: list[Issue] = []
+    if total > LINE_BUDGET:
+        issues.append(
+            Issue("(all)", 0, f"Over line budget: {total} lines (max {LINE_BUDGET})")
+        )
+    return issues, counts, total
+
+
+def check_staleness(files: list[Path]) -> list[Issue]:
+    src_files = list(ROOT.glob("src/**/*.py"))
+    if not src_files:
+        return []
+    newest_src = max(src_files, key=lambda f: f.stat().st_mtime)
+    newest_mtime = newest_src.stat().st_mtime
+    issues: list[Issue] = []
+    for doc in files:
+        if doc.stat().st_mtime < newest_mtime:
+            issues.append(
+                Issue(
+                    str(doc.relative_to(ROOT)),
+                    0,
+                    f"Older than {newest_src.relative_to(ROOT)} — may be stale",
+                )
+            )
+    return issues
+
+
+def main() -> None:
+    print("Auditing docs...\n")
+    files = find_instruction_files()
+    scripts = load_scripts()
+    issues: list[Issue] = []
+
+    for doc in files:
+        rel = str(doc.relative_to(ROOT))
+        content = doc.read_text()
+        issues.extend(check_tree_paths(rel, content))
+        issues.extend(check_scripts(rel, content, scripts))
+        issues.extend(check_type_conventions(rel, content))
+
+    budget_issues, counts, total = check_line_budget(files)
+    issues.extend(budget_issues)
+    issues.extend(check_staleness(files))
+
+    for issue in issues:
+        loc = f"  {issue.file}"
+        if issue.line:
+            loc += f":{issue.line}"
+        print(f"{loc:<35} ✗ {issue.message}")
+
+    mark = "✓" if total <= LINE_BUDGET else "✗"
+    print(f"\nCombined instruction files: {total} lines (budget: {LINE_BUDGET}) {mark}")
+    for name, n in sorted(counts.items()):
+        print(f"  {name}: {n}")
+
+    n = len(issues)
+    print(f"\nFound {n} issue(s)" if n else "\nNo issues found ✓")
+    sys.exit(1 if n else 0)
+
+
+if __name__ == "__main__":
+    main()

collab/__init__.py

@@ -0,0 +1,81 @@
+"""Collaborator configuration — parse collaborators.toml."""
+
+import tomllib
+from pathlib import Path
+
+import msgspec
+
+CONFIG_PATH = Path("collaborators.toml")
+
+
+class Collaborator(msgspec.Struct):
+    labels: list[str]
+    repo: str = ""
+    github_user: str = ""
+    name: str = ""
+    account: str = ""
+
+
+def collab_dir(collab: Collaborator) -> Path:
+    """Return the local collab directory (correspondence/for/{gh_user}/)."""
+    return Path("correspondence") / "for" / collab.github_user.lower()
+
+
+def _auto_repo(owner_gh: str, collab_gh: str) -> str:
+    """Derive the default repo name: {owner}/to-{collab}."""
+    return f"{owner_gh}/to-{collab_gh.lower()}"
+
+
+def load_collaborators(path: Path | None = None) -> dict[str, Collaborator]:
+    """Load collaborators.toml and return {github_user: Collaborator} mapping.
+
+    The TOML section key is the collaborator's GitHub username.
+    ``repo`` is auto-derived from owner config if not explicitly set.
+    """
+    if path is None:
+        path = CONFIG_PATH
+    if not path.exists():
+        return {}
+    with open(path, "rb") as f:
+        raw = tomllib.load(f)
+    # Load owner for repo auto-derivation
+    owner_gh = ""
+    try:
+        from accounts import load_owner
+
+        owner = load_owner()
+        owner_gh = owner.github_user
+    except (SystemExit, ImportError):
+        pass
+
+    result: dict[str, Collaborator] = {}
+    for gh_user, data in raw.items():
+        collab = msgspec.convert(data, Collaborator)
+        # github_user is always the TOML key
+        collab = msgspec.structs.replace(collab, github_user=gh_user)
+        # Auto-derive repo if not explicit
+        if not collab.repo and owner_gh:
+            collab = msgspec.structs.replace(collab, repo=_auto_repo(owner_gh, gh_user))
+        result[gh_user] = collab
+    return result
+
+
+def save_collaborators(
+    collabs: dict[str, Collaborator], path: Path | None = None
+) -> None:
+    """Write collaborators back to TOML. Simple serializer — no third-party dep."""
+    if path is None:
+        path = CONFIG_PATH
+    lines: list[str] = []
+    for gh_user, c in sorted(collabs.items()):
+        lines.append(f"[{gh_user}]")
+        labels = ", ".join(f'"{lbl}"' for lbl in c.labels)
+        lines.append(f"labels = [{labels}]")
+        if c.name:
+            lines.append(f'name = "{c.name}"')
+        if c.repo:
+            lines.append(f'repo = "{c.repo}"')
+        if c.account:
+            lines.append(f'account = "{c.account}"')
+        lines.append("")
+    path.write_text("\n".join(lines), encoding="utf-8")