devin-devkit 0.1.0__tar.gz

devin_devkit-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: devin-devkit
+Version: 0.1.0
+Summary: Install public Devin CLI profiles through uv
+Author: Icaro0310
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+<div align="center">
+
+<a href="https://github.com/Icaro0310/devin-devkit/actions/workflows/test-devkit.yml"><img src="https://github.com/Icaro0310/devin-devkit/actions/workflows/test-devkit.yml/badge.svg" alt="ci"/></a>
+
+<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-devkit"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-devkit/badge" alt="OpenSSF Scorecard"/></a>
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"/></a>
+<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"/></a>
+<a href="https://github.com/Icaro0310/devin-devkit"><img src="https://img.shields.io/github/stars/Icaro0310/devin-devkit" alt="GitHub stars"/></a>
+<a href="https://github.com/Icaro0310/devin-devkit/commits/main"><img src="https://img.shields.io/github/last-commit/Icaro0310/devin-devkit" alt="Last commit"/></a>
+<a href="https://github.com/Icaro0310/awesome-devin"><img src="https://img.shields.io/badge/part%20of-devin--*-ecosystem-7c3aed" alt="devin-* ecosystem"/></a>
+<a href="https://github.com/Icaro0310/devin-devkit/issues"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"/></a>
+</div>
+
+# devin-devkit
+
+> Unofficial community project. Not affiliated with, endorsed by, or sponsored by Cognition AI. Devin is a Cognition AI trademark.
+
+**[Linux](README.linux.md)** · **[Personal Windows](README.windows.md)** · **[Corporate Windows](README.corporate-windows.md)** · **[Compatibility](COMPATIBILITY.md)** · **[macOS status](README.macos.md)**
+
+Part of the [awesome-devin](https://github.com/Icaro0310/awesome-devin) ecosystem: the curated hub for the devin-* tools.
+
+`devin-devkit` turns the public `devin-powerups` registry into selectable installation profiles. It is an **installer/distribution tool**, not a meta-package: each Python app gets its own isolated `uv` environment, and the Node bridge uses npm separately.
+
+![devin-devkit demo: list, outdated, doctor check](assets/demo.gif)
+
+## Source → tools → profiles
+
+- `devin-powerups/registry.json` is the catalog and profile source of truth for the first-party `devin-*` tools, this separate DevKit distribution, the maintainer hub, and related artifacts.
+- `tools/export_devkit_manifest.py` builds this repo's bundled manifest from the registry, including artifact, interface, audience, platform and environment metadata. The exporter rejects private or unregistered tools and verifies immutable Git commit references.
+- `src/devin_devkit/cli.py` previews and installs the selected profile under an explicit execution environment. It does not edit Devin settings, inspect session databases, or install Slack/Obsidian/VM services.
+
+## Execution environments
+
+One `devin-devkit` distribution supports three environments. Linux and Personal Windows use the extended runtime: local execution plus optional delegated workloads through Devin VM or QwenPaw when the selected tool supports them. Corporate Windows is intentionally self-contained: local execution only, with no VM, QwenPaw, Slack dependency, external compute, or workload delegation.
+
+The installer defaults to `linux` on Linux and `personal-windows` on Windows. Corporate Windows is never inferred from the operating system; select it explicitly so restricted machines fail closed:
+
+```bash
+devin-devkit install qa --environment linux
+devin-devkit install qa --environment personal-windows
+devin-devkit install qa --environment corporate-windows
+```
+
+Environment entry points: [Linux](environments/linux/README.md) · [Personal Windows](environments/personal-windows/README.md) · [Corporate Windows](environments/corporate-windows/README.md).
+
+The generated [compatibility matrix](COMPATIBILITY.md) is rendered from `registry.json`; unsupported entries carry an explicit registry reason rather than guessed compatibility.
+
+## Profiles
+
+| Profile | Contents |
+|---|---|
+| `qa` | internals spec, QA pack, evals, metrics, doctor |
+| `evaluation` | internals spec, evals, metrics, synthetic task fixtures |
+| `security` | redact, bridge, janitor |
+| `memory` / `agent` | memory, graph, search, poordjaevin |
+| `operations` | backup, history, doctor, metrics, janitor, PM, orchestrator, switch and skill catalog |
+| `full` / `all` | every automatically installable profile tool; `devin-office` remains a manual source-only service |
+
+QwenPaw is an optional add-on and is not installed by these profiles. macOS is planned, not tested.
+
+## Use
+
+Install the current GitHub source archive or use a local checkout; the package has no runtime dependencies:
+
+```bash
+uv tool install "git+https://github.com/Icaro0310/devin-devkit.git#subdirectory=packages/devkit"
+```
+
+From a local checkout, use `uv tool install .`. Then inspect the available profiles and preview before applying:
+
+```bash
+devin-devkit profiles
+devin-devkit list
+devin-devkit install qa
+devin-devkit install qa --apply
+devin-devkit install full --apply
+```
+
+Install specs are pinned (PyPI versions or GitHub archive SHAs), so an install never drifts on its own. To move forward:
+
+```bash
+devin-devkit outdated          # which installed tools have newer pins
+devin-devkit update            # preview the update plan
+devin-devkit update --apply    # reinstall outdated tools
+devin-devkit update --force --apply   # reinstall everything
+```
+
+`outdated`/`update` read the manifest published in this repository, which a weekly workflow re-exports from the maintainer registry, so the pins are never more than about a week behind upstream.
+
+To run from a checkout without installing the DevKit itself:
+
+```bash
+uv run --project . python -m devin_devkit.cli install qa
+```
+
+After a PyPI package release, the installer can also be run with `uvx devin-devkit ...`.
+
+The manifest pins PyPI versions where available and GitHub source archives to immutable commit SHAs otherwise. Before it starts, the installer checks platform support, registry-declared environment compatibility, required managers, Node.js for `devin-bridge`, and existing command collisions. It never overwrites an existing command; commands already on `PATH` are reported as pre-existing but are not version-verified, and a partial collision blocks the profile before any installs run.
+
+## Runtime requirements
+
+- Python tools: Python 3.10 or newer, installed in isolated environments managed by `uv`.
+- `devin-bridge`: Node.js 20 or newer and npm. Its pinned GitHub archive is downloaded over HTTPS.
+- Current installable profiles do not need Git. Git is needed only for manual source checkouts such as `devin-office`; package archives use HTTPS.
+- Supported environments: Linux, Personal Windows and Corporate Windows. Linux and Personal Windows may use optional delegated runtime; Corporate Windows rejects registry entries that require external runtime, delegation or external integrations. macOS is planned but not claimed as tested.
+
+## Development and synchronization
+
+```bash
+uv run --extra dev pytest
+python ../devin-powerups/tools/validate_registry.py
+python ../devin-powerups/tools/export_devkit_manifest.py
+python ../devin-powerups/tools/export_devkit_manifest.py --check
+python ../devin-powerups/tools/render_catalog.py --check ../Icaro0310/README.md
+```
+
+The DevKit package has no runtime dependencies. New catalog entries and profiles belong in the registry; regenerate the manifest instead of hand-editing its generated copy. For local sibling development, install dependencies editably in a virtual environment (examples in the OS guides); keep relative file paths out of publishable package metadata.

devin_devkit-0.1.0/README.md

@@ -0,0 +1,117 @@
+<div align="center">
+
+<a href="https://github.com/Icaro0310/devin-devkit/actions/workflows/test-devkit.yml"><img src="https://github.com/Icaro0310/devin-devkit/actions/workflows/test-devkit.yml/badge.svg" alt="ci"/></a>
+
+<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-devkit"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-devkit/badge" alt="OpenSSF Scorecard"/></a>
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"/></a>
+<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"/></a>
+<a href="https://github.com/Icaro0310/devin-devkit"><img src="https://img.shields.io/github/stars/Icaro0310/devin-devkit" alt="GitHub stars"/></a>
+<a href="https://github.com/Icaro0310/devin-devkit/commits/main"><img src="https://img.shields.io/github/last-commit/Icaro0310/devin-devkit" alt="Last commit"/></a>
+<a href="https://github.com/Icaro0310/awesome-devin"><img src="https://img.shields.io/badge/part%20of-devin--*-ecosystem-7c3aed" alt="devin-* ecosystem"/></a>
+<a href="https://github.com/Icaro0310/devin-devkit/issues"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"/></a>
+</div>
+
+# devin-devkit
+
+> Unofficial community project. Not affiliated with, endorsed by, or sponsored by Cognition AI. Devin is a Cognition AI trademark.
+
+**[Linux](README.linux.md)** · **[Personal Windows](README.windows.md)** · **[Corporate Windows](README.corporate-windows.md)** · **[Compatibility](COMPATIBILITY.md)** · **[macOS status](README.macos.md)**
+
+Part of the [awesome-devin](https://github.com/Icaro0310/awesome-devin) ecosystem: the curated hub for the devin-* tools.
+
+`devin-devkit` turns the public `devin-powerups` registry into selectable installation profiles. It is an **installer/distribution tool**, not a meta-package: each Python app gets its own isolated `uv` environment, and the Node bridge uses npm separately.
+
+![devin-devkit demo: list, outdated, doctor check](assets/demo.gif)
+
+## Source → tools → profiles
+
+- `devin-powerups/registry.json` is the catalog and profile source of truth for the first-party `devin-*` tools, this separate DevKit distribution, the maintainer hub, and related artifacts.
+- `tools/export_devkit_manifest.py` builds this repo's bundled manifest from the registry, including artifact, interface, audience, platform and environment metadata. The exporter rejects private or unregistered tools and verifies immutable Git commit references.
+- `src/devin_devkit/cli.py` previews and installs the selected profile under an explicit execution environment. It does not edit Devin settings, inspect session databases, or install Slack/Obsidian/VM services.
+
+## Execution environments
+
+One `devin-devkit` distribution supports three environments. Linux and Personal Windows use the extended runtime: local execution plus optional delegated workloads through Devin VM or QwenPaw when the selected tool supports them. Corporate Windows is intentionally self-contained: local execution only, with no VM, QwenPaw, Slack dependency, external compute, or workload delegation.
+
+The installer defaults to `linux` on Linux and `personal-windows` on Windows. Corporate Windows is never inferred from the operating system; select it explicitly so restricted machines fail closed:
+
+```bash
+devin-devkit install qa --environment linux
+devin-devkit install qa --environment personal-windows
+devin-devkit install qa --environment corporate-windows
+```
+
+Environment entry points: [Linux](environments/linux/README.md) · [Personal Windows](environments/personal-windows/README.md) · [Corporate Windows](environments/corporate-windows/README.md).
+
+The generated [compatibility matrix](COMPATIBILITY.md) is rendered from `registry.json`; unsupported entries carry an explicit registry reason rather than guessed compatibility.
+
+## Profiles
+
+| Profile | Contents |
+|---|---|
+| `qa` | internals spec, QA pack, evals, metrics, doctor |
+| `evaluation` | internals spec, evals, metrics, synthetic task fixtures |
+| `security` | redact, bridge, janitor |
+| `memory` / `agent` | memory, graph, search, poordjaevin |
+| `operations` | backup, history, doctor, metrics, janitor, PM, orchestrator, switch and skill catalog |
+| `full` / `all` | every automatically installable profile tool; `devin-office` remains a manual source-only service |
+
+QwenPaw is an optional add-on and is not installed by these profiles. macOS is planned, not tested.
+
+## Use
+
+Install the current GitHub source archive or use a local checkout; the package has no runtime dependencies:
+
+```bash
+uv tool install "git+https://github.com/Icaro0310/devin-devkit.git#subdirectory=packages/devkit"
+```
+
+From a local checkout, use `uv tool install .`. Then inspect the available profiles and preview before applying:
+
+```bash
+devin-devkit profiles
+devin-devkit list
+devin-devkit install qa
+devin-devkit install qa --apply
+devin-devkit install full --apply
+```
+
+Install specs are pinned (PyPI versions or GitHub archive SHAs), so an install never drifts on its own. To move forward:
+
+```bash
+devin-devkit outdated          # which installed tools have newer pins
+devin-devkit update            # preview the update plan
+devin-devkit update --apply    # reinstall outdated tools
+devin-devkit update --force --apply   # reinstall everything
+```
+
+`outdated`/`update` read the manifest published in this repository, which a weekly workflow re-exports from the maintainer registry, so the pins are never more than about a week behind upstream.
+
+To run from a checkout without installing the DevKit itself:
+
+```bash
+uv run --project . python -m devin_devkit.cli install qa
+```
+
+After a PyPI package release, the installer can also be run with `uvx devin-devkit ...`.
+
+The manifest pins PyPI versions where available and GitHub source archives to immutable commit SHAs otherwise. Before it starts, the installer checks platform support, registry-declared environment compatibility, required managers, Node.js for `devin-bridge`, and existing command collisions. It never overwrites an existing command; commands already on `PATH` are reported as pre-existing but are not version-verified, and a partial collision blocks the profile before any installs run.
+
+## Runtime requirements
+
+- Python tools: Python 3.10 or newer, installed in isolated environments managed by `uv`.
+- `devin-bridge`: Node.js 20 or newer and npm. Its pinned GitHub archive is downloaded over HTTPS.
+- Current installable profiles do not need Git. Git is needed only for manual source checkouts such as `devin-office`; package archives use HTTPS.
+- Supported environments: Linux, Personal Windows and Corporate Windows. Linux and Personal Windows may use optional delegated runtime; Corporate Windows rejects registry entries that require external runtime, delegation or external integrations. macOS is planned but not claimed as tested.
+
+## Development and synchronization
+
+```bash
+uv run --extra dev pytest
+python ../devin-powerups/tools/validate_registry.py
+python ../devin-powerups/tools/export_devkit_manifest.py
+python ../devin-powerups/tools/export_devkit_manifest.py --check
+python ../devin-powerups/tools/render_catalog.py --check ../Icaro0310/README.md
+```
+
+The DevKit package has no runtime dependencies. New catalog entries and profiles belong in the registry; regenerate the manifest instead of hand-editing its generated copy. For local sibling development, install dependencies editably in a virtual environment (examples in the OS guides); keep relative file paths out of publishable package metadata.

devin_devkit-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "devin-devkit"
+version = "0.1.0"
+description = "Install public Devin CLI profiles through uv"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Icaro0310" }]
+dependencies = [
+  "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+devin-devkit = "devin_devkit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+devin_devkit = ["manifest.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

devin_devkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

devin_devkit-0.1.0/src/devin_devkit/__init__.py

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

devin_devkit-0.1.0/src/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-0.1.0/src/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"]}