devin-devkit 0.1.0__py3-none-any.whl

devin_devkit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

devin_devkit/cli.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from devin_devkit.installer import DevKitError, apply_plan, build_plan, load_manifest
+from devin_devkit.updater import (
+    apply_update_plan,
+    build_update_plan,
+    fetch_remote_manifest,
+    freshness_hint,
+)
+
+
+def _print_plan(plan: dict[str, Any], as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(plan, ensure_ascii=False, indent=2))
+        return
+    print(f"Profile: {plan['profile']} ({plan['platform']}; environment={plan['environment']}; runtime={plan['runtime']})")
+    for item in plan["actions"]:
+        command = " ".join(item.get("command", []))
+        detail = item.get("detail", "")
+        suffix = f" — {detail}" if detail else ""
+        print(f"- {item['tool']}: {item['action']}{suffix}{': ' + command if command else ''}")
+    for error in plan["errors"]:
+        print(f"BLOCKED: {error}", file=sys.stderr)
+    if not plan["errors"] and any(item["action"] == "install" for item in plan["actions"]):
+        print("Dry run only. Re-run with --apply to install.")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="devin-devkit", description="Install curated Devin tool profiles with isolated uv/npm environments.")
+    parser.add_argument("--manifest", type=Path, help=argparse.SUPPRESS)
+    sub = parser.add_subparsers(dest="action", required=True)
+    sub.add_parser("profiles", help="list available installation profiles")
+    sub.add_parser("list", help="list the tools in the manifest")
+    install = sub.add_parser("install", help="preview a profile; pass --apply to install")
+    install.add_argument("profile")
+    install.add_argument("--apply", action="store_true", help="install the selected profile")
+    install.add_argument("--json", action="store_true", help="print the plan as JSON")
+    install.add_argument(
+        "--environment",
+        choices=["linux", "personal-windows", "corporate-windows"],
+        help="execution environment; defaults to linux on Linux and personal-windows on Windows",
+    )
+    outdated = sub.add_parser("outdated", help="list installed tools with a newer version in the remote registry")
+    outdated.add_argument("--json", action="store_true", help="print the check as JSON")
+    update = sub.add_parser("update", help="preview tool updates; pass --apply to install them")
+    update.add_argument("--apply", action="store_true", help="reinstall outdated tools")
+    update.add_argument("--force", action="store_true", help="reinstall every installed tool")
+    update.add_argument("--json", action="store_true", help="print the plan as JSON")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        manifest = load_manifest(args.manifest)
+        if args.action in {"outdated", "update"}:
+            remote = fetch_remote_manifest()
+            plan = build_update_plan(remote, force=args.action == "update" and args.force)
+            if args.json:
+                print(json.dumps(plan, ensure_ascii=False, indent=2))
+            else:
+                print(f"Remote registry v{plan['registry_version']} (generated {plan['generated']})")
+                for item in plan["actions"]:
+                    if item["action"] == "update":
+                        print(f"- {item['tool']}: {item['from']} -> {item['to']}")
+                    elif item["action"] == "current":
+                        print(f"- {item['tool']}: up to date ({item['version']})")
+                    elif item["action"] == "blocked":
+                        print(f"- {item['tool']}: BLOCKED — {item['detail']}")
+            if args.action == "outdated":
+                return 0
+            pending = [a for a in plan["actions"] if a["action"] == "update"]
+            if not args.apply:
+                if pending:
+                    print("Dry run only. Re-run with --apply to update.")
+                return 0
+            result = apply_update_plan(plan)
+            print(f"Updated: {', '.join(result['updated']) or 'nothing'}")
+            for name in result["failed"]:
+                print(f"FAILED: {name}", file=sys.stderr)
+            return 1 if result["failed"] else 0
+        if args.action == "profiles":
+            for name, profile in manifest["profiles"].items():
+                alias = f" (alias of {profile['alias_of']})" if profile.get("alias_of") else ""
+                print(f"{name}: {profile['label']}{alias} — {profile['description']}")
+            return 0
+        if args.action == "list":
+            cat = manifest["catalog"]
+            pl = lambda n: "" if n == 1 else "s"  # noqa: E731
+            print(f"{cat['tool_count']} first-party Devin tools; {cat['distribution_count']} distribution layer{pl(cat['distribution_count'])}; {cat['hub_count']} maintainer hub{pl(cat['hub_count'])}; {cat['related_count']} related project{pl(cat['related_count'])}")
+            for tool in manifest["tools"]:
+                print(f"{tool['id']}: {tool['package']} {tool['version']} [{tool['manager']}/{tool['source']}/{tool['status']}]")
+            hint = freshness_hint(manifest)
+            if hint:
+                print(hint, file=sys.stderr)
+            return 0
+
+        plan = build_plan(manifest, args.profile, environment=args.environment)
+        if not args.apply:
+            _print_plan(plan, args.json)
+            hint = freshness_hint(manifest)
+            if hint:
+                print(hint, file=sys.stderr)
+            return 2 if plan["errors"] else 0
+        if plan["errors"]:
+            _print_plan(plan, args.json)
+            return 2
+        result = apply_plan(plan)
+        print(json.dumps(result, ensure_ascii=False, indent=2) if args.json else f"Installed: {', '.join(result['installed']) or 'nothing new'}")
+        for item in result["actions"]:
+            if item["action"] in {"preexisting", "manual", "unsupported"}:
+                detail = item.get("detail", ", ".join(item.get("commands", [])))
+                print(f"- {item['tool']}: {item['action']} — {detail}")
+        return 0
+    except DevKitError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devin_devkit/installer.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import json
+import platform as platform_module
+import re
+import shutil
+import subprocess
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, Callable
+
+
+class DevKitError(RuntimeError):
+    pass
+
+
+def load_manifest(path: Path | None = None) -> dict[str, Any]:
+    source = path if path is not None else files("devin_devkit").joinpath("manifest.json")
+    try:
+        text = Path(source).read_text(encoding="utf-8") if path else source.read_text(encoding="utf-8")
+        return json.loads(text)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise DevKitError(f"cannot load manifest {source}: {exc}") from exc
+
+
+def platform_name(system: str | None = None) -> str:
+    value = (system or platform_module.system()).lower()
+    if value in {"nt", "windows"}:
+        return "windows"
+    if value in {"posix", "linux"}:
+        return "linux"
+    if value in {"darwin", "macos"}:
+        return "macos"
+    return value
+
+
+_ENVIRONMENT_ALIASES = {
+    "linux": "linux",
+    "personal-windows": "personal_windows",
+    "personal_windows": "personal_windows",
+    "windows": "personal_windows",
+    "corporate-windows": "corporate_windows",
+    "corporate_windows": "corporate_windows",
+    "corporate": "corporate_windows",
+}
+
+
+def normalize_environment(environment: str | None, host: str) -> str:
+    if environment is None:
+        return "personal_windows" if host == "windows" else host
+    normalized = _ENVIRONMENT_ALIASES.get(environment.lower())
+    if normalized is None:
+        raise ValueError(f"unsupported environment: {environment}")
+    expected_host = "windows" if normalized.endswith("_windows") else normalized
+    if host != expected_host:
+        raise ValueError(f"environment {normalized} cannot run on host platform {host}")
+    return normalized
+
+
+def resolve_profile(manifest: dict[str, Any], name: str) -> tuple[str, dict[str, Any]]:
+    profiles = manifest.get("profiles", {})
+    if name not in profiles:
+        raise DevKitError(f"unknown profile {name!r}; choose from: {', '.join(sorted(profiles))}")
+    current = name
+    seen: set[str] = set()
+    while profiles[current].get("alias_of"):
+        if current in seen:
+            raise DevKitError(f"profile alias cycle at {current!r}")
+        seen.add(current)
+        current = profiles[current]["alias_of"]
+        if current not in profiles:
+            raise DevKitError(f"profile {name!r} points to missing alias target {current!r}")
+    return current, profiles[current]
+
+
+def _node_major(runner: Callable[..., Any], which: Callable[[str], str | None]) -> int | None:
+    if which("node") is None:
+        return None
+    try:
+        result = runner(["node", "--version"], capture_output=True, text=True, check=False)
+    except OSError:
+        return None
+    match = re.search(r"v?(\d+)", result.stdout or "")
+    return int(match.group(1)) if match else None
+
+
+def build_plan(
+    manifest: dict[str, Any],
+    profile_name: str,
+    *,
+    system: str | None = None,
+    environment: str | None = None,
+    which: Callable[[str], str | None] = shutil.which,
+    runner: Callable[..., Any] = subprocess.run,
+) -> dict[str, Any]:
+    resolved_name, profile = resolve_profile(manifest, profile_name)
+    host = platform_name(system)
+    if host not in manifest.get("supported_platforms", []):
+        planned = ", ".join(manifest.get("planned_platforms", [])) or "none"
+        raise DevKitError(f"platform {host!r} is not supported; planned platforms: {planned}")
+    try:
+        selected_environment = normalize_environment(environment, host)
+    except ValueError as exc:
+        raise DevKitError(str(exc)) from exc
+    if selected_environment not in manifest.get("environments", {}):
+        raise DevKitError(f"manifest does not define environment {selected_environment!r}")
+
+    tool_map = {tool["id"]: tool for tool in manifest.get("tools", [])}
+    actions: list[dict[str, Any]] = []
+    errors: list[str] = []
+    node_major = None
+
+    for tool_id in profile.get("tools", []):
+        tool = tool_map.get(tool_id)
+        if tool is None:
+            errors.append(f"profile {resolved_name!r} references unknown tool {tool_id!r}")
+            continue
+        environment_meta = tool.get("environments", {}).get(selected_environment)
+        if environment_meta is None:
+            errors.append(f"{tool_id} has no {selected_environment} environment metadata")
+            actions.append({"tool": tool_id, "action": "unsupported", "detail": f"no metadata for {selected_environment}"})
+            continue
+        if not environment_meta.get("supported"):
+            reason = environment_meta.get("reason", f"not listed for {selected_environment}")
+            errors.append(f"{tool_id} is unsupported in {selected_environment}: {reason}")
+            actions.append({"tool": tool_id, "action": "unsupported", "detail": reason})
+            continue
+        if selected_environment == "corporate_windows" and (
+            environment_meta.get("external_dependencies") or environment_meta.get("delegation") in {"optional", "supported", "required"}
+        ):
+            reason = "external runtime or delegation is disabled in corporate Windows"
+            errors.append(f"{tool_id} violates the corporate Windows local-only guarantee")
+            actions.append({"tool": tool_id, "action": "blocked", "detail": reason})
+            continue
+        if host not in tool.get("platforms", []):
+            actions.append({"tool": tool_id, "action": "unsupported", "detail": f"not listed for {host}"})
+            continue
+        if tool.get("status") == "manual" or tool.get("manager") == "manual":
+            actions.append({"tool": tool_id, "action": "manual", "detail": tool.get("manual_note", "manual setup required")})
+            continue
+
+        manager = tool["manager"]
+        commands = tool.get("commands", [])
+        present = [command for command in commands if which(command) is not None]
+        if present:
+            if len(present) == len(commands):
+                actions.append({"tool": tool_id, "action": "preexisting", "detail": "commands are on PATH; versions are not verified", "commands": present})
+            else:
+                missing = [command for command in commands if command not in present]
+                errors.append(f"{tool_id} has a partial PATH collision; present={present}, missing={missing}")
+                actions.append({"tool": tool_id, "action": "blocked", "detail": "partial command collision"})
+            continue
+
+        manager_binary = "uv" if manager == "uv" else "npm"
+        if which(manager_binary) is None:
+            errors.append(f"{tool_id} requires {manager_binary} on PATH")
+            actions.append({"tool": tool_id, "action": "blocked", "detail": f"missing {manager_binary}"})
+            continue
+        if tool.get("requires_git") and which("git") is None:
+            errors.append(f"{tool_id} has a Git dependency and requires git on PATH")
+            actions.append({"tool": tool_id, "action": "blocked", "detail": "missing git"})
+            continue
+        if manager == "npm":
+            if node_major is None:
+                node_major = _node_major(runner, which)
+            if node_major is None or node_major < 20:
+                errors.append(f"{tool_id} requires Node.js >=20")
+                actions.append({"tool": tool_id, "action": "blocked", "detail": "Node.js >=20 is required"})
+                continue
+
+        spec = tool.get("install_spec")
+        if not spec:
+            errors.append(f"{tool_id} has no install specification")
+            actions.append({"tool": tool_id, "action": "blocked", "detail": "missing install specification"})
+            continue
+        command = ["uv", "tool", "install", spec] if manager == "uv" else ["npm", "install", "--global", spec]
+        actions.append({"tool": tool_id, "action": "install", "command": command})
+
+    manual = [
+        {"tool": name, "action": "manual", "detail": tool_map.get(name, {}).get("manual_note", "manual setup required")}
+        for name in profile.get("manual", [])
+    ]
+    actions.extend(manual)
+    return {
+        "profile": profile_name,
+        "resolved_profile": resolved_name,
+        "platform": host,
+        "environment": selected_environment,
+        "runtime": manifest["environments"][selected_environment].get("runtime"),
+        "dry_run": True,
+        "actions": actions,
+        "errors": errors,
+    }
+
+
+def apply_plan(plan: dict[str, Any], runner: Callable[..., Any] = subprocess.run) -> dict[str, Any]:
+    if plan["errors"]:
+        raise DevKitError("preflight failed: " + "; ".join(plan["errors"]))
+    completed: list[str] = []
+    for action in plan["actions"]:
+        if action["action"] != "install":
+            continue
+        try:
+            result = runner(action["command"], check=False)
+        except OSError as exc:
+            raise DevKitError(f"failed to start {action['tool']}: {exc}") from exc
+        if result.returncode:
+            raise DevKitError(
+                f"install failed for {action['tool']} (exit {result.returncode}); "
+                f"completed before failure: {completed}"
+            )
+        completed.append(action["tool"])
+    return {"profile": plan["profile"], "installed": completed, "actions": plan["actions"]}