devin-switch 0.1.0__py3-none-any.whl

devin_switch/__init__.py

@@ -0,0 +1,12 @@
+"""devin-switch — switch between Devin configuration profiles.
+
+Manages the config files in the Devin config/data dirs (``User/settings.json``,
+``config.json`` hooks, ``mcp_config.json`` MCP entries) as declarative
+profiles, with verified snapshots before any write and a rollback journal.
+
+``credentials.toml`` is never touched — not even read.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

devin_switch/cli.py

@@ -0,0 +1,320 @@
+"""Thin CLI wrapper — all logic lives in the library modules.
+
+- ``devin-switch list`` — discovered profiles (read-only)
+- ``devin-switch show <profile>`` — what the profile manages (read-only)
+- ``devin-switch diff <a> <b>`` — masked per-file diff between two profiles
+- ``devin-switch use <profile>`` — DRY-RUN by default; ``--apply`` writes
+- ``devin-switch rollback`` — DRY-RUN by default; ``--apply`` restores the
+  last journal backup
+- ``devin-switch doctor`` — config sanity + closest-profile ranking
+
+Exit codes: 0 on success / clean dry-run; 1 on any error (unknown profile,
+nothing to roll back, snapshot verification failure) or — for ``doctor``
+only — on any FAIL check. ``credentials.toml`` is never touched, ever.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from devin_switch import engine, journal
+from devin_switch import paths as paths_mod
+from devin_switch.health import check_config_files, rank_profiles
+from devin_switch.paths import Roots, target_for
+from devin_switch.plan import (
+    build_plan,
+    profile_diff,
+    render_plan,
+    summarize_json_top_keys,
+)
+from devin_switch.profiles import ProfileError, discover, get
+from devin_switch.redact import is_credential_file, is_never_touch
+
+
+def _add_roots(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--data-dir",
+        type=Path,
+        default=None,
+        help="Devin data dir (default: platform location — "
+        "%%APPDATA%%/devin on Windows, ~/.config/devin elsewhere)",
+    )
+    p.add_argument(
+        "--config-dir",
+        type=Path,
+        default=None,
+        help="Devin UI config dir holding User/ (default: platform "
+        "location; falls back to --data-dir when only that is given)",
+    )
+    p.add_argument(
+        "--profiles-dir",
+        type=Path,
+        default=None,
+        help="directory of profile overlays (default: "
+        "$DEVIN_SWITCH_PROFILES_DIR, ./profiles, or bundled examples)",
+    )
+
+
+def _add_apply(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--apply",
+        action="store_true",
+        help="WRITE MODE: perform the switch after a verified snapshot. "
+        "Without it the command is a dry-run and writes nothing.",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="devin-switch",
+        description="Switch between Devin configuration profiles (hooks, "
+        "MCP, models) with snapshot and verification. Read-only unless "
+        "--apply is passed; credentials.toml is never touched.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_list = sub.add_parser("list", help="list discovered profiles")
+    _add_roots(p_list)
+
+    p_show = sub.add_parser(
+        "show", help="show what a profile manages (values masked)"
+    )
+    _add_roots(p_show)
+    p_show.add_argument("profile")
+
+    p_diff = sub.add_parser(
+        "diff", help="masked diff between two profiles (read-only)"
+    )
+    _add_roots(p_diff)
+    p_diff.add_argument("a")
+    p_diff.add_argument("b")
+
+    p_use = sub.add_parser(
+        "use", help="preview a switch (dry-run) or apply it with --apply"
+    )
+    _add_roots(p_use)
+    _add_apply(p_use)
+    p_use.add_argument("profile")
+
+    p_rb = sub.add_parser(
+        "rollback",
+        help="preview restoring the last backup (dry-run) or restore it "
+        "with --apply",
+    )
+    _add_roots(p_rb)
+    _add_apply(p_rb)
+
+    p_doc = sub.add_parser(
+        "doctor",
+        help="config sanity checks + closest-profile ranking (read-only)",
+    )
+    _add_roots(p_doc)
+
+    return parser
+
+
+def _roots(args: argparse.Namespace) -> Roots:
+    data_dir = (args.data_dir or paths_mod.default_data_dir()).expanduser()
+    if args.config_dir is not None:
+        config_dir = args.config_dir.expanduser()
+    elif args.data_dir is not None:
+        # single-root mode: one dir holds both data files and User/
+        config_dir = data_dir
+    else:
+        config_dir = paths_mod.default_config_dir()
+    return Roots(
+        data_dir=data_dir,
+        config_dir=config_dir,
+        profiles_dir=paths_mod.resolve_profiles_dir(args.profiles_dir),
+    )
+
+
+# ---------------------------------------------------------------------------
+# subcommands
+# ---------------------------------------------------------------------------
+
+
+def cmd_list(roots: Roots) -> int:
+    profiles = discover(roots.profiles_dir)
+    if not profiles:
+        print(f"no profiles found in {roots.profiles_dir}")
+        print("create profiles/<name>/ with config overlays — see README")
+        return 0
+    print(f"profiles in {roots.profiles_dir}:")
+    for profile in profiles.values():
+        n = len(profile.files)
+        desc = f" — {profile.description}" if profile.description else ""
+        print(f"  {profile.name:<16} {n:>2} file(s){desc}")
+    return 0
+
+
+def cmd_show(roots: Roots, name: str) -> int:
+    profile = get(roots.profiles_dir, name)
+    print(f"profile: {profile.name}")
+    print(f"root:    {profile.root}")
+    if profile.description:
+        print(f"desc:    {profile.description}")
+    for note in profile.notes:
+        print(f"note:    {note}")
+    print("files:")
+    for rel in sorted(profile.files):
+        src = profile.files[rel]
+        size = src.stat().st_size
+        if is_never_touch(rel):
+            target_desc = "(never managed — skipped)"
+        else:
+            try:
+                target_desc = str(target_for(rel, roots))
+            except ValueError as exc:
+                target_desc = f"(unsafe — {exc})"
+        print(f"  {rel}  [{size} B]")
+        print(f"    -> {target_desc}")
+        if is_credential_file(rel) or is_never_touch(rel):
+            print("    keys: <withheld — credential-carrying file>")
+            continue
+        keys = summarize_json_top_keys(src.read_bytes())
+        if keys:
+            print(f"    keys: {', '.join(keys)}")
+    return 0
+
+
+def cmd_diff(roots: Roots, a: str, b: str) -> int:
+    profile_a = get(roots.profiles_dir, a)
+    profile_b = get(roots.profiles_dir, b)
+    print(f"diff {a} -> {b} (values masked):")
+    print(profile_diff(profile_a, profile_b))
+    return 0
+
+
+def _plan_counts(plans) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for fp in plans:
+        counts[fp.action] = counts.get(fp.action, 0) + 1
+    return counts
+
+
+def cmd_use(roots: Roots, name: str, apply: bool) -> int:
+    profile = get(roots.profiles_dir, name)
+    plans = build_plan(profile, roots)
+    counts = _plan_counts(plans)
+    summary = ", ".join(
+        f"{n} {action}" for action, n in sorted(counts.items())
+    )
+    if not apply:
+        print(f"DRY-RUN use {name} — nothing will be written ({summary})")
+        print(render_plan(plans))
+        print()
+        print("re-run with --apply to snapshot, verify and write")
+        return 0
+    try:
+        result = engine.apply_plan(name, plans, roots)
+    except engine.SnapshotError as exc:
+        print(f"ABORTED — snapshot verification failed; no files written",
+              file=sys.stderr)
+        for problem in exc.problems:
+            print(f"  {problem}", file=sys.stderr)
+        print(f"  (backup kept for inspection: {exc.backup_dir})",
+              file=sys.stderr)
+        return 1
+    if result.files_changed:
+        print(f"applied profile '{name}' — {len(result.files_changed)} "
+              "file(s) written:")
+        for rel in result.files_changed:
+            print(f"  wrote {rel}")
+        print(f"backup: {result.backup_dir}")
+    else:
+        print(f"profile '{name}' already in effect — nothing to write")
+    if result.skipped:
+        print(f"skipped (never managed): {', '.join(result.skipped)}")
+    print(f"journal: {roots.journal_path}")
+    print("undo:    devin-switch rollback --apply")
+    return 0
+
+
+def cmd_rollback(roots: Roots, apply: bool) -> int:
+    entry = journal.last_use_entry(roots.journal_path)
+    if entry is None:
+        print("nothing to roll back — no 'use' entry with an existing "
+              "backup in the journal", file=sys.stderr)
+        return 1
+    try:
+        steps = engine.plan_rollback(entry, roots)
+    except (FileNotFoundError, engine.SnapshotError, ValueError) as exc:
+        print(f"cannot roll back: {exc}", file=sys.stderr)
+        return 1
+    if not apply:
+        print(f"DRY-RUN rollback — would undo 'use {entry.get('profile')}' "
+              f"from {entry.get('ts')} (nothing written)")
+        for step in steps:
+            verb = "restore" if step.action == "restore" else "delete  "
+            print(f"  {verb} {step.target}")
+        print()
+        print("re-run with --apply to restore the backup")
+        return 0
+    result = engine.apply_rollback(entry, steps, roots)
+    print(f"rolled back to pre-'use {result.profile}' state:")
+    for step in result.steps:
+        verb = "restored" if step.action == "restore" else "deleted "
+        print(f"  {verb} {step.target}")
+    print(f"journal: {roots.journal_path}")
+    return 0
+
+
+def cmd_doctor(roots: Roots) -> int:
+    results = check_config_files(roots)
+    worst = 0
+    for r in results:
+        print(f"{r.status:<4} {r.label} — {r.detail}")
+        if r.status == "FAIL":
+            worst = 1
+    print()
+    profiles = discover(roots.profiles_dir)
+    if profiles:
+        ranked = rank_profiles(profiles, roots)
+        best, dist = ranked[0]
+        noun = "file" if dist == 1 else "files"
+        state = "exactly matches" if dist == 0 else f"{dist} {noun} away"
+        print(f"closest profile: {best.name} ({state})")
+        for profile, d in ranked[1:]:
+            noun = "file" if d == 1 else "files"
+            print(f"  {profile.name}: {d} {noun} away")
+    else:
+        print(f"no profiles in {roots.profiles_dir} — nothing to rank")
+    return worst
+
+
+# ---------------------------------------------------------------------------
+# entry point
+# ---------------------------------------------------------------------------
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    args = build_parser().parse_args(argv)
+    roots = _roots(args)
+    try:
+        if args.command == "list":
+            return cmd_list(roots)
+        if args.command == "show":
+            return cmd_show(roots, args.profile)
+        if args.command == "diff":
+            return cmd_diff(roots, args.a, args.b)
+        if args.command == "use":
+            return cmd_use(roots, args.profile, args.apply)
+        if args.command == "rollback":
+            return cmd_rollback(roots, args.apply)
+        if args.command == "doctor":
+            return cmd_doctor(roots)
+    except ProfileError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devin_switch/engine.py

@@ -0,0 +1,256 @@
+"""The write path — snapshot, verify, apply, rollback.
+
+Order of operations for ``use <profile> --apply``:
+
+1. snapshot every managed file the profile will change into
+   ``.devin-ecosystem/switch-backups/<ts>/`` (files that do not exist yet
+   are recorded as ``existed: false`` in the manifest — nothing copied);
+2. verify sha256 of every backup copy against both the recorded hash and
+   the live source — refuse to write anything on mismatch;
+3. write the overlay atomically (sibling tmp file + ``os.replace``);
+4. append the journal entry.
+
+``credentials.toml`` is excluded upstream (``plan`` marks it ``skip``) and
+never reaches this module's file loops.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from devin_switch import journal
+from devin_switch.paths import Roots, target_for
+from devin_switch.plan import FilePlan
+
+MANIFEST_NAME = "manifest.json"
+
+
+class SnapshotError(Exception):
+    """Snapshot verification failed — nothing was applied."""
+
+    def __init__(self, problems: list[str], backup_dir: Path):
+        self.problems = problems
+        self.backup_dir = backup_dir
+        super().__init__("; ".join(problems))
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def atomic_write(target: Path, data: bytes) -> None:
+    """Write via a sibling tmp file + ``os.replace`` (same-dir rename is
+    atomic on POSIX and Windows)."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    tmp = target.with_name(target.name + ".devin-switch.tmp")
+    tmp.write_bytes(data)
+    os.replace(tmp, target)
+
+
+def _unique_backup_dir(roots: Roots, stamp: str) -> Path:
+    base = roots.backups_dir / stamp
+    candidate, i = base, 1
+    while candidate.exists():
+        i += 1
+        candidate = Path(f"{base}-{i}")
+    return candidate
+
+
+@dataclass
+class ApplyResult:
+    profile: str
+    files_changed: list[str]
+    backup_dir: Path | None
+    journal_entry: dict[str, Any] | None
+    skipped: list[str]
+
+
+def snapshot(
+    plans: list[FilePlan], backup_dir: Path, roots: Roots
+) -> dict[str, Any]:
+    """Copy the pre-switch bytes of every file about to change.
+
+    The manifest records, per managed file: the profile-relative path, the
+    absolute target, whether it existed and its sha256 (when it did).
+    """
+    backup_dir.mkdir(parents=True, exist_ok=False)
+    files: list[dict[str, Any]] = []
+    for fp in plans:
+        if not fp.needs_write:
+            continue
+        record: dict[str, Any] = {
+            "rel": fp.rel,
+            "target": str(fp.target),
+            "existed": fp.old_bytes is not None,
+            "sha256": None,
+        }
+        if fp.old_bytes is not None:
+            dest = backup_dir / fp.rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(fp.target, dest)
+            record["sha256"] = sha256_file(dest)
+        files.append(record)
+    manifest = {
+        "version": 1,
+        "files": files,
+    }
+    (backup_dir / MANIFEST_NAME).write_text(
+        json.dumps(manifest, indent=2), encoding="utf-8"
+    )
+    return manifest
+
+
+def verify_snapshot(manifest: dict[str, Any], backup_dir: Path) -> list[str]:
+    """Every backup copy must hash to its recorded sha256 AND still match
+    the live source file (which could have changed mid-switch)."""
+    problems: list[str] = []
+    for record in manifest.get("files", []):
+        if not record.get("existed"):
+            continue
+        rel, recorded = record["rel"], record["sha256"]
+        copy = backup_dir / rel
+        if not copy.is_file():
+            problems.append(f"{rel}: backup copy missing")
+            continue
+        if sha256_file(copy) != recorded:
+            problems.append(f"{rel}: backup copy sha256 mismatch")
+            continue
+        source = Path(record["target"])
+        if not source.is_file() or sha256_file(source) != recorded:
+            problems.append(
+                f"{rel}: source changed between snapshot and verify"
+            )
+    return problems
+
+
+def apply_plan(
+    profile_name: str, plans: list[FilePlan], roots: Roots
+) -> ApplyResult:
+    """Snapshot → verify → write → journal. Raises ``SnapshotError``
+    before any file is written when verification fails."""
+    changed = [fp for fp in plans if fp.needs_write]
+    skipped = [fp.rel for fp in plans if fp.action == "skip"]
+    if not changed:
+        entry = journal.append(
+            roots.journal_path, "use", profile_name, [], None
+        )
+        return ApplyResult(profile_name, [], None, entry, skipped)
+
+    backup_dir = _unique_backup_dir(roots, journal.backup_stamp())
+    manifest = snapshot(changed, backup_dir, roots)
+    problems = verify_snapshot(manifest, backup_dir)
+    if problems:
+        # Leave the backup dir in place — it is the evidence of what the
+        # files looked like when the switch was attempted.
+        raise SnapshotError(problems, backup_dir)
+
+    for fp in changed:
+        atomic_write(fp.target, fp.new_bytes)
+
+    files_changed = [fp.rel for fp in changed]
+    entry = journal.append(
+        roots.journal_path, "use", profile_name, files_changed, backup_dir
+    )
+    return ApplyResult(profile_name, files_changed, backup_dir, entry, skipped)
+
+
+# ---------------------------------------------------------------------------
+# rollback
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RollbackStep:
+    rel: str
+    target: Path
+    action: str  # "restore" | "delete"
+    backup_copy: Path | None
+
+
+@dataclass
+class RollbackResult:
+    profile: str
+    steps: list[RollbackStep]
+    journal_entry: dict[str, Any]
+
+
+def _load_manifest(backup_dir: Path) -> dict[str, Any]:
+    manifest_path = backup_dir / MANIFEST_NAME
+    if not manifest_path.is_file():
+        raise FileNotFoundError(
+            f"backup manifest missing: {manifest_path}"
+        )
+    return json.loads(manifest_path.read_text(encoding="utf-8"))
+
+
+def plan_rollback(entry: dict[str, Any], roots: Roots) -> list[RollbackStep]:
+    """Steps to undo a ``use`` entry: restore files that existed, delete
+    files the switch created."""
+    backup_dir = Path(entry["backup_dir"])
+    manifest = _load_manifest(backup_dir)
+    steps: list[RollbackStep] = []
+    for record in manifest.get("files", []):
+        rel = record["rel"]
+        target = Path(record["target"])
+        if record["existed"]:
+            copy = backup_dir / rel
+            expected = record.get("sha256")
+            if not copy.is_file():
+                raise FileNotFoundError(
+                    f"backup copy missing for {rel}: {copy}"
+                )
+            if expected and sha256_file(copy) != expected:
+                raise SnapshotError(
+                    [f"{rel}: backup copy sha256 mismatch — refusing to "
+                     "restore a corrupted snapshot"],
+                    backup_dir,
+                )
+            steps.append(RollbackStep(rel, target, "restore", copy))
+        else:
+            steps.append(RollbackStep(rel, target, "delete", None))
+    return steps
+
+
+def _prune_empty_dirs(path: Path, stop_at: Path) -> None:
+    path = path.parent
+    while path != stop_at and stop_at in path.parents:
+        try:
+            path.rmdir()
+        except OSError:
+            break
+        path = path.parent
+
+
+def apply_rollback(
+    entry: dict[str, Any], steps: list[RollbackStep], roots: Roots
+) -> RollbackResult:
+    for step in steps:
+        if step.action == "restore":
+            assert step.backup_copy is not None
+            atomic_write(step.target, step.backup_copy.read_bytes())
+        else:
+            if step.target.is_file():
+                step.target.unlink()
+            _prune_empty_dirs(step.target, roots.data_dir)
+            _prune_empty_dirs(step.target, roots.config_dir)
+    files_changed = [s.rel for s in steps]
+    entry_out = journal.append(
+        roots.journal_path,
+        "rollback",
+        str(entry.get("profile", "")),
+        files_changed,
+        None,
+    )
+    return RollbackResult(
+        str(entry.get("profile", "")), steps, entry_out
+    )