@mriekki/project-forge 4.13.5 → 4.14.1

package/README.md

@@ -94,6 +94,8 @@ clone repository
 
 Project Forge supports independent workspace instances on multiple developer computers. Git/GitHub is the shared source boundary; local databases, credentials, SSH keys/trust, Docker state, and readiness stay workstation-local.
 
+On Windows, Project Forge defaults compatible development to **WSL2 with Ubuntu**: keep repositories in the WSL Linux filesystem (normally `~/projects`), run shells/toolchains from WSL, keep desktop UI applications on Windows, and use Docker Desktop with its WSL2 backend/integration rather than installing a second Docker Engine inside the distro. Native Windows remains valid for Projects with a real Windows-specific requirement. Existing Windows checkouts can be migrated non-destructively with [`tools/windows/project-forge-wsl2.ps1`](tools/windows/project-forge-wsl2.ps1); see [`docs/WINDOWS_WSL2.md`](docs/WINDOWS_WSL2.md).
+
 ## Public ChatGPT contract
 
 Project Forge's public ChatGPT bootstrap entrypoint is [`chatgpt/START_HERE.md`](chatgpt/START_HERE.md).

package/assets/bootstrap-migrations/wsl-setup/setup-launcher.manifest.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "id": "bootstrap-wsl2-setup-launcher",
+  "owner": "bootstrap",
+  "destination": "scripts/setup.sh",
+  "asset": "assets/bootstrap-migrations/wsl-setup/setup.sh",
+  "source": {
+    "component": "bootstrap",
+    "revision": "173203baaf36935d04eb81c89f1d016131a40442",
+    "artifact": "templates/scripts/setup.sh.tpl"
+  },
+  "targetGitBlob": "4e8c48a3d33c6a8ae4534ec860c2ee0205e417aa",
+  "supportedPredecessorGitBlobs": [
+    "ec941c079da066785ac628d6bbb7dd6b668494f2"
+  ],
+  "supportedBootstrapRevisions": [
+    "0c45eb332a815ad79ea061443f337500b9dc5712"
+  ]
+}

package/assets/bootstrap-migrations/wsl-setup/setup-wsl.manifest.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "id": "bootstrap-wsl2-setup-runtime",
+  "owner": "bootstrap",
+  "destination": "tools/dev-environment/setup-wsl.py",
+  "asset": "assets/bootstrap-migrations/wsl-setup/setup-wsl.py",
+  "source": {
+    "component": "bootstrap",
+    "revision": "173203baaf36935d04eb81c89f1d016131a40442",
+    "artifact": "runtime/dev_environment_wsl.py"
+  },
+  "targetGitBlob": "6731910246fb99887c58b9f3a8a14fec1bf02c01",
+  "supportedPredecessorGitBlobs": [],
+  "supportedBootstrapRevisions": [
+    "0c45eb332a815ad79ea061443f337500b9dc5712"
+  ],
+  "allowMissing": true
+}

package/assets/bootstrap-migrations/wsl-setup/setup-wsl.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[2]
+CONFIG = ROOT / "DEV_ENVIRONMENT.json"
+CATALOG = ROOT / "tools" / "dev-environment" / "catalog"
+
+
+class SetupError(RuntimeError):
+    pass
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise SetupError(f"Missing required file: {path}") from exc
+
+
+def run(args: list[str], *, capture: bool = True) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        args,
+        cwd=str(ROOT),
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        capture_output=capture,
+        check=False,
+    )
+
+
+def is_wsl() -> bool:
+    if os.environ.get("WSL_DISTRO_NAME"):
+        return True
+    try:
+        release = Path("/proc/sys/kernel/osrelease").read_text(encoding="utf-8").lower()
+    except OSError:
+        return False
+    return "microsoft" in release or "wsl" in release
+
+
+def command_path(command: str) -> str | None:
+    return shutil.which(command)
+
+
+def version_ok(spec: dict[str, Any], version: str | None) -> tuple[bool, str]:
+    command = spec["command"]
+    if not command_path(command):
+        return False, "missing"
+    result = run([command, *spec.get("verifyArgs", [])])
+    detail = "\n".join(filter(None, [(result.stdout or "").strip(), (result.stderr or "").strip()]))
+    if result.returncode != 0:
+        return False, detail or f"exit {result.returncode}"
+    if not version:
+        return True, detail
+
+    handler = spec.get("handler")
+    if handler == "major-version":
+        found = re.search(r"(\d+)\.", detail)
+        return bool(found and found.group(1) == version.split(".")[0]), detail
+    if handler == "java-major":
+        found = re.search(r'(?:(?:version|openjdk)\s+\")?(\d+)', detail, flags=re.IGNORECASE)
+        return bool(found and found.group(1) == version.split(".")[0]), detail
+    return version in detail, detail
+
+
+def ensure_apt_package(package: str) -> None:
+    if run(["dpkg", "-s", package]).returncode == 0:
+        return
+    result = run(["sudo", "apt-get", "update"], capture=False)
+    if result.returncode != 0:
+        raise SetupError("apt-get update failed; rerun from an interactive WSL terminal with sudo access")
+    result = run(["sudo", "apt-get", "install", "-y", package], capture=False)
+    if result.returncode != 0:
+        raise SetupError(f"Unable to install required Ubuntu package: {package}")
+
+
+def ensure_fnm_node(version: str | None, check_only: bool) -> tuple[bool, str, str]:
+    if not command_path("fnm"):
+        return False, "fnm is missing in WSL; install fnm inside the distro before rerunning /setup", "MISSING"
+    if not version:
+        return True, "fnm available", "PASS"
+    result = run(["fnm", "exec", f"--using={version}", "--", "node", "--version"])
+    detail = "\n".join(filter(None, [(result.stdout or "").strip(), (result.stderr or "").strip()]))
+    if result.returncode == 0 and version in detail.lstrip("v"):
+        return True, detail, "PASS"
+    if check_only:
+        return False, detail or f"Node {version} is not installed through fnm", "VERSION_MISMATCH"
+    install = run(["fnm", "install", version], capture=False)
+    if install.returncode != 0:
+        return False, f"fnm failed to install Node {version}", "FAILED"
+    run(["fnm", "default", version], capture=False)
+    verify = run(["fnm", "exec", f"--using={version}", "--", "node", "--version"])
+    text = (verify.stdout or verify.stderr or "").strip()
+    return verify.returncode == 0 and version in text.lstrip("v"), text, "PASS" if verify.returncode == 0 else "FAILED"
+
+
+def ensure_tool(entry: dict[str, Any], check_only: bool) -> tuple[bool, str, str]:
+    tool_id = entry["id"]
+    spec = read_json(CATALOG / f"{tool_id}.json")
+    version = entry.get("version")
+
+    if tool_id == "node":
+        return ensure_fnm_node(version, check_only)
+
+    ok, detail = version_ok(spec, version)
+    if ok:
+        if tool_id == "docker":
+            operational = run(["docker", "info", "--format", "{{.ServerVersion}}"])
+            operational_detail = (operational.stdout or operational.stderr or "").strip()
+            if operational.returncode != 0:
+                return False, (
+                    "Docker CLI is present but Docker Desktop is not operational through WSL integration. "
+                    "Start Docker Desktop and enable this distro under Settings > Resources > WSL Integration. "
+                    "Do not install a second Docker Engine inside WSL."
+                ), "NOT_OPERATIONAL"
+            return True, operational_detail, "PASS"
+        return True, detail, "PASS"
+
+    if check_only:
+        return False, detail, "MISSING" if detail == "missing" else "VERSION_MISMATCH"
+
+    apt_packages = {
+        "git": "git",
+        "github-cli": "gh",
+        "python": "python3",
+        "sqlite": "sqlite3",
+        "ssh": "openssh-client",
+        "go": "golang-go",
+    }
+    if tool_id in apt_packages:
+        ensure_apt_package(apt_packages[tool_id])
+        ok, detail = version_ok(spec, version)
+        return ok, detail, "PASS" if ok else "FAILED"
+
+    if tool_id == "vscode":
+        return False, (
+            "VS Code's WSL command bridge is unavailable. Install VS Code on Windows and the "
+            "Remote - WSL extension, then open this repository with `code .` from WSL."
+        ), "MISSING"
+    if tool_id == "docker":
+        return False, (
+            "Docker is unavailable inside WSL. Install/start Docker Desktop on Windows and enable "
+            "WSL integration for this distro; do not install Docker Engine inside WSL."
+        ), "MISSING"
+    if tool_id == "fnm":
+        return False, (
+            "fnm is required inside WSL for Project-declared Node versions. Install fnm in this "
+            "distro, then rerun /setup."
+        ), "MISSING"
+    if tool_id == "dotnet":
+        return False, (
+            f".NET SDK {version or ''} is required inside WSL. Install the matching Microsoft .NET SDK "
+            "for Ubuntu in this distro, then rerun /setup."
+        ).strip(), "MISSING" if detail == "missing" else "VERSION_MISMATCH"
+    if tool_id == "java":
+        return False, (
+            f"Java {version or ''} is required inside WSL. Install the matching JDK in this distro, "
+            "then rerun /setup."
+        ).strip(), "MISSING" if detail == "missing" else "VERSION_MISMATCH"
+
+    return False, detail or f"No WSL installer is defined for {tool_id}", "MISSING"
+
+
+def ensure_extensions(extensions: list[str], check_only: bool) -> list[str]:
+    if not extensions or not command_path("code"):
+        return extensions if not command_path("code") else []
+    result = run(["code", "--list-extensions"])
+    installed = {line.strip().lower() for line in (result.stdout or "").splitlines() if line.strip()}
+    missing = [value for value in extensions if value.lower() not in installed]
+    if not check_only:
+        for extension in missing:
+            run(["code", "--install-extension", extension, "--force"], capture=False)
+        result = run(["code", "--list-extensions"])
+        installed = {line.strip().lower() for line in (result.stdout or "").splitlines() if line.strip()}
+        missing = [value for value in extensions if value.lower() not in installed]
+    return missing
+
+
+def restore_project(commands: list[list[str]], check_only: bool) -> list[str]:
+    if check_only:
+        return []
+    plan_path = ROOT / "SCAFFOLD_PLAN.json"
+    if plan_path.exists():
+        plan = read_json(plan_path)
+        missing_markers = [marker for marker in plan.get("markers", []) if not (ROOT / marker).exists()]
+        if missing_markers:
+            print("DEFERRED project restore — scaffold markers are not present")
+            return []
+    failures: list[str] = []
+    for command in commands:
+        if not command:
+            continue
+        result = run(command, capture=False)
+        if result.returncode != 0:
+            failures.append(" ".join(command))
+    return failures
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Prepare/verify a Project Forge developer environment in WSL2")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--restore", action="store_true")
+    args = parser.parse_args()
+
+    if not is_wsl():
+        raise SetupError("This Linux setup runtime is supported only inside WSL2 for the current Windows development profile.")
+    if str(ROOT).startswith("/mnt/"):
+        raise SetupError(
+            "This Project is under a Windows-mounted filesystem. Project Forge's Windows default requires "
+            "a Linux-native WSL checkout such as ~/projects/<repo>. Migrate the repository first."
+        )
+
+    config = read_json(CONFIG)
+    declared = set(config.get("platforms", []))
+    if not ({"windows", "linux"} & declared):
+        raise SetupError("This Project does not declare a Windows/WSL-compatible development environment")
+
+    print(f"== Developer environment (WSL2: {os.environ.get('WSL_DISTRO_NAME', 'Linux')}) ==")
+    failed_required: list[str] = []
+    failed_optional: list[str] = []
+    for entry in config.get("tools", []):
+        required = entry.get("required", True)
+        ok, detail, state = ensure_tool(entry, args.check)
+        version = f" {entry['version']}" if entry.get("version") else ""
+        first = detail.splitlines()[0] if detail else ""
+        print(f"{state} {entry['id']}{version}" + (f" — {first}" if first else ""))
+        if not ok:
+            (failed_required if required else failed_optional).append(entry["id"])
+
+    missing_extensions = ensure_extensions(config.get("vscodeExtensions", []), args.check)
+    for extension in missing_extensions:
+        print(f"MISSING extension {extension}")
+    if missing_extensions:
+        failed_required.append("VS Code extensions")
+
+    restore_failures = restore_project(config.get("projectRestore", []), args.check) if args.restore else []
+    if restore_failures:
+        failed_required.append("project restore")
+
+    if failed_optional:
+        print("Optional tools not ready: " + ", ".join(failed_optional))
+    if failed_required:
+        print("Required environment items not ready: " + ", ".join(failed_required), file=sys.stderr)
+        return 2
+
+    print("Project Forge WSL2 setup: PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except SetupError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        raise SystemExit(2)

package/assets/bootstrap-migrations/wsl-setup/setup.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SETUP_ENGINE="$ROOT/tools/dev-environment/setup.py"
+WSL_SETUP_ENGINE="$ROOT/tools/dev-environment/setup-wsl.py"
+
+if [[ "$(/usr/bin/uname -s)" == "Linux" ]]; then
+  if [[ -z "${WSL_DISTRO_NAME:-}" ]] && ! /bin/grep -Eqi '(microsoft|wsl)' /proc/sys/kernel/osrelease 2>/dev/null; then
+    echo "ERROR: this generated Linux setup path currently supports WSL2 only." >&2
+    exit 2
+  fi
+
+  PYTHON_BIN="$(command -v python3 || true)"
+  if [[ -z "$PYTHON_BIN" ]]; then
+    if [[ " ${*:-} " == *" --check "* ]]; then
+      echo "ERROR: python3 is required to run the read-only Project Forge WSL2 setup check." >&2
+      exit 2
+    fi
+    echo "Project Forge: installing the Python setup runtime inside WSL."
+    sudo apt-get update
+    sudo apt-get install -y python3
+    PYTHON_BIN="$(command -v python3 || true)"
+    if [[ -z "$PYTHON_BIN" ]]; then
+      echo "ERROR: python3 installation completed but python3 is still unavailable." >&2
+      exit 2
+    fi
+  fi
+
+  exec "$PYTHON_BIN" "$WSL_SETUP_ENGINE" "$@"
+fi
+
+# Project Forge treats Homebrew as the macOS package-management substrate for
+# generated workstation setup. Keep the installer immutable and verify the
+# exact Git blob before executing it; never execute Homebrew/install HEAD.
+HOMEBREW_INSTALL_REVISION="85d1a3fc80d8a63932f632aca8f787de11d14a64"
+HOMEBREW_INSTALL_BLOB_SHA="30615f54182a9d600455ad979783f3cebcdc58aa"
+HOMEBREW_INSTALL_URL="https://raw.githubusercontent.com/Homebrew/install/${HOMEBREW_INSTALL_REVISION}/install.sh"
+
+CHECK_ONLY=0
+for argument in "$@"; do
+  if [[ "$argument" == "--check" ]]; then
+    CHECK_ONLY=1
+    break
+  fi
+done
+
+find_brew() {
+  local candidate
+  if command -v brew >/dev/null 2>&1; then
+    command -v brew
+    return 0
+  fi
+  for candidate in /opt/homebrew/bin/brew /usr/local/bin/brew; do
+    if [[ -x "$candidate" ]]; then
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+activate_brew() {
+  local brew_bin="$1"
+  local python_prefix=""
+  eval "$("$brew_bin" shellenv)"
+
+  # Homebrew intentionally keeps unversioned Python shims such as `python`
+  # under the Python formula's libexec/bin. The generated catalog historically
+  # probes `python`, so expose that formula-owned directory to this setup
+  # process without modifying the developer's shell startup files.
+  python_prefix="$("$brew_bin" --prefix python 2>/dev/null || true)"
+  if [[ -n "$python_prefix" && -d "$python_prefix/libexec/bin" ]]; then
+    export PATH="$python_prefix/libexec/bin:$PATH"
+  fi
+}
+
+verify_homebrew_installer() {
+  local installer="$1"
+  local size actual
+  size="$(/usr/bin/wc -c < "$installer" | /usr/bin/tr -d '[:space:]')"
+  actual="$({ printf 'blob %s\0' "$size"; /bin/cat "$installer"; } | /usr/bin/shasum -a 1 | /usr/bin/awk '{print $1}')"
+  if [[ "$actual" != "$HOMEBREW_INSTALL_BLOB_SHA" ]]; then
+    echo "ERROR: Homebrew installer integrity mismatch." >&2
+    echo "Expected Git blob $HOMEBREW_INSTALL_BLOB_SHA but got $actual." >&2
+    return 2
+  fi
+}
+
+install_homebrew() {
+  local installer
+  if [[ "$(/usr/bin/uname -s)" != "Darwin" ]]; then
+    echo "ERROR: macOS setup launcher cannot bootstrap Homebrew on this platform." >&2
+    return 2
+  fi
+  if [[ ! -x /usr/bin/curl ]]; then
+    echo "ERROR: macOS setup requires /usr/bin/curl to bootstrap Homebrew." >&2
+    return 2
+  fi
+  if [[ ! -x /usr/bin/shasum ]]; then
+    echo "ERROR: macOS setup requires /usr/bin/shasum to verify the Homebrew installer." >&2
+    return 2
+  fi
+
+  installer="$(/usr/bin/mktemp "${TMPDIR:-/tmp}/project-forge-homebrew.XXXXXX")"
+  if ! /usr/bin/curl -fsSL "$HOMEBREW_INSTALL_URL" -o "$installer"; then
+    /bin/rm -f "$installer"
+    echo "ERROR: Unable to download the pinned Homebrew installer." >&2
+    return 2
+  fi
+  if ! verify_homebrew_installer "$installer"; then
+    /bin/rm -f "$installer"
+    return 2
+  fi
+
+  echo "Project Forge: Homebrew is required for supported macOS tool installation."
+  echo "Project Forge: running verified Homebrew installer ${HOMEBREW_INSTALL_REVISION}."
+  if [[ -t 0 ]]; then
+    if ! /bin/bash "$installer"; then
+      /bin/rm -f "$installer"
+      echo "ERROR: Homebrew bootstrap did not complete." >&2
+      echo "If macOS requested administrator or Command Line Tools approval, complete that native prompt and rerun /setup." >&2
+      return 2
+    fi
+  else
+    if ! NONINTERACTIVE=1 /bin/bash "$installer"; then
+      /bin/rm -f "$installer"
+      echo "ERROR: Homebrew bootstrap needs macOS administrator or Command Line Tools interaction that is unavailable in this non-interactive terminal." >&2
+      echo "Rerun /setup from an interactive terminal; Project Forge will continue the same setup flow without requiring manual install commands." >&2
+      return 2
+    fi
+  fi
+  /bin/rm -f "$installer"
+}
+
+preflight_interactive_casks() {
+  local pending
+  pending="$("$PYTHON_BIN" - "$ROOT" "$BREW_BIN" <<'PY'
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+root = Path(sys.argv[1])
+brew = sys.argv[2]
+config = json.loads((root / "DEV_ENVIRONMENT.json").read_text(encoding="utf-8"))
+catalog = root / "tools" / "dev-environment" / "catalog"
+pending = []
+for entry in config.get("tools", []):
+    spec = json.loads((catalog / f"{entry['id']}.json").read_text(encoding="utf-8"))
+    install = spec.get("install", {}).get("macos") or {}
+    if install.get("interactive") is not True:
+        continue
+    package = install.get("package")
+    if not package and install.get("packageTemplate"):
+        version = entry.get("version")
+        if not version:
+            continue
+        package = install["packageTemplate"].format(major=version.split(".")[0], version=version)
+    if not package:
+        continue
+    result = subprocess.run(
+        [brew, "list", "--cask", package],
+        check=False,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    if result.returncode != 0:
+        pending.append(f"{entry['id']} ({package})")
+print(", ".join(pending))
+PY
+)"
+
+  if [[ -z "$pending" ]]; then
+    return 0
+  fi
+
+  echo "Project Forge: macOS interactive-install preflight: $pending"
+  echo "Project Forge: these declared tools may require an administrator/native installer prompt during this setup run."
+  if [[ ! -t 0 ]]; then
+    echo "ERROR: required macOS tool installation needs an interactive terminal before Project Forge starts the install sequence." >&2
+    echo "Rerun this same generated setup command from an interactive terminal; do not install the listed packages manually." >&2
+    return 2
+  fi
+}
+
+BREW_BIN="$(find_brew || true)"
+if [[ -z "$BREW_BIN" && "$CHECK_ONLY" -eq 0 ]]; then
+  install_homebrew
+  BREW_BIN="$(find_brew || true)"
+  if [[ -z "$BREW_BIN" ]]; then
+    echo "ERROR: Homebrew installation completed but brew is still unavailable." >&2
+    exit 2
+  fi
+fi
+
+if [[ -n "$BREW_BIN" ]]; then
+  activate_brew "$BREW_BIN"
+fi
+
+PYTHON_BIN="$(command -v python3 || true)"
+if [[ -z "$PYTHON_BIN" ]]; then
+  if [[ "$CHECK_ONLY" -eq 1 ]]; then
+    echo "ERROR: python3 is required to run the read-only Project Forge setup check." >&2
+    exit 2
+  fi
+  if [[ -z "$BREW_BIN" ]]; then
+    echo "ERROR: Homebrew is unavailable, so Project Forge cannot install the Python setup runtime." >&2
+    exit 2
+  fi
+
+  echo "Project Forge: installing the Python setup runtime through Homebrew."
+  "$BREW_BIN" install python
+  activate_brew "$BREW_BIN"
+  PYTHON_BIN="$(command -v python3 || true)"
+  if [[ -z "$PYTHON_BIN" ]]; then
+    echo "ERROR: Homebrew installed Python but python3 is still unavailable." >&2
+    exit 2
+  fi
+fi
+
+if [[ "$CHECK_ONLY" -eq 0 && -n "$BREW_BIN" ]]; then
+  preflight_interactive_casks
+fi
+
+exec "$PYTHON_BIN" "$SETUP_ENGINE" "$@"

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.13.5",
+  "version": "4.14.1",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {

package/assets/generated/ASSEMBLY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.13.5",
+  "version": "4.14.1",
   "components": {
     "core": {
       "revision": "b51cb62bcc9630748168c9fd1900c6109cafb587",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.13.5",
+  "version": "4.14.1",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bin/",
     "src/",
     "assets/",
+    "tools/",
     "README.md"
   ],
   "scripts": {

package/src/bootstrap-migrations.mjs

@@ -2,7 +2,11 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
-const MANIFEST_RELATIVE = 'assets/bootstrap-migrations/managed-baseline-verifier/manifest.json';
+const MANIFEST_RELATIVES = [
+  'assets/bootstrap-migrations/managed-baseline-verifier/manifest.json',
+  'assets/bootstrap-migrations/wsl-setup/setup-launcher.manifest.json',
+  'assets/bootstrap-migrations/wsl-setup/setup-wsl.manifest.json'
+];
 const BOOTSTRAP_MANIFEST = 'PROJECT_BOOTSTRAP.json';
 
 function readJson(file) {
@@ -37,8 +41,23 @@ function safeConsumerPath(root, relative) {
   return resolved;
 }
 
-function loadManifest(packageData) {
-  const file = path.join(packageData.root, ...MANIFEST_RELATIVE.split('/'));
+function assertSafeExistingPath(root, destination, relative, kind = 'file') {
+  const stat = fs.lstatSync(destination);
+  if (kind === 'file' && (!stat.isFile() || stat.isSymbolicLink())) {
+    throw new Error(`Bootstrap migration destination is not a regular file: ${relative}`);
+  }
+  if (kind === 'directory' && (!stat.isDirectory() || stat.isSymbolicLink())) {
+    throw new Error(`Bootstrap migration parent is not a regular directory: ${relative}`);
+  }
+  const realRoot = fs.realpathSync(root);
+  const realDestination = fs.realpathSync(destination);
+  if (realDestination !== realRoot && !realDestination.startsWith(`${realRoot}${path.sep}`)) {
+    throw new Error(`Bootstrap migration path resolves outside the Project root: ${relative}`);
+  }
+}
+
+function loadManifest(packageData, manifestRelative) {
+  const file = path.join(packageData.root, ...manifestRelative.split('/'));
   const manifest = readJson(file);
   if (manifest.schemaVersion !== 1 || manifest.owner !== 'bootstrap') {
     throw new Error('Invalid Bootstrap migration manifest ownership/schema');
@@ -56,105 +75,156 @@ function loadManifest(packageData) {
   if (!Array.isArray(manifest.supportedPredecessorGitBlobs) || !manifest.supportedPredecessorGitBlobs.every((value) => /^[0-9a-f]{40}$/.test(value))) {
     throw new Error('Invalid Bootstrap migration predecessor identities');
   }
+  if (manifest.supportedBootstrapRevisions !== undefined && (
+    !Array.isArray(manifest.supportedBootstrapRevisions)
+    || !manifest.supportedBootstrapRevisions.every((value) => /^[0-9a-f]{40}$/.test(value))
+  )) {
+    throw new Error('Invalid Bootstrap migration supported Bootstrap revisions');
+  }
+  if (manifest.allowMissing !== undefined && typeof manifest.allowMissing !== 'boolean') {
+    throw new Error('Invalid Bootstrap migration allowMissing value');
+  }
   const assetRelative = safeRelative(manifest.asset, 'Bootstrap migration bundled asset');
   const asset = path.join(packageData.root, ...assetRelative.split('/'));
   const bytes = fs.readFileSync(asset);
   if (gitBlobSha(bytes) !== manifest.targetGitBlob) {
-    throw new Error('Bundled Bootstrap migration asset identity does not match its manifest');
+    throw new Error(`Bundled Bootstrap migration asset identity does not match its manifest: ${manifest.id}`);
   }
   return { manifest, bytes };
 }
 
+function loadManifests(packageData) {
+  return MANIFEST_RELATIVES.map((relative) => loadManifest(packageData, relative));
+}
+
+function appliesToBootstrap(manifest, bootstrap) {
+  if (!manifest.supportedBootstrapRevisions) return true;
+  const revision = bootstrap?.bootstrap?.commit;
+  return typeof revision === 'string' && manifest.supportedBootstrapRevisions.includes(revision);
+}
+
+function migrationState(manifest) {
+  return manifest.id === 'bootstrap-managed-baseline-verifier-schema2'
+    ? 'MIGRATE_BOOTSTRAP_VERIFIER'
+    : 'MIGRATE_BOOTSTRAP_FILE';
+}
+
 export function planBootstrapMigrations(packageData, consumerRoot) {
   const bootstrapManifest = path.join(consumerRoot, BOOTSTRAP_MANIFEST);
   if (!fs.existsSync(bootstrapManifest)) return { rows: [], unsafe: [] };
 
-  const { manifest } = loadManifest(packageData);
-  const destination = safeConsumerPath(consumerRoot, manifest.destination);
-  if (!fs.existsSync(destination)) {
-    return {
-      rows: [],
-      unsafe: [{
-        owner: 'bootstrap',
-        state: 'BOOTSTRAP_MIGRATION_UNSUPPORTED',
-        path: manifest.destination,
-        detail: 'Bootstrap-generated verifier is missing; refusing package mutation before a supported migration is established.'
-      }]
-    };
-  }
+  const bootstrap = readJson(bootstrapManifest);
+  const rows = [];
+  const unsafe = [];
 
-  const stat = fs.lstatSync(destination);
-  if (!stat.isFile() || stat.isSymbolicLink()) {
-    return {
-      rows: [],
-      unsafe: [{
+  for (const { manifest } of loadManifests(packageData)) {
+    if (!appliesToBootstrap(manifest, bootstrap)) continue;
+
+    const destination = safeConsumerPath(consumerRoot, manifest.destination);
+    if (!fs.existsSync(destination)) {
+      if (manifest.allowMissing) {
+        const parent = path.dirname(destination);
+        try {
+          if (!fs.existsSync(parent)) throw new Error('parent missing');
+          assertSafeExistingPath(consumerRoot, parent, path.dirname(manifest.destination), 'directory');
+          rows.push({
+            owner: 'bootstrap',
+            state: 'ADD_BOOTSTRAP_FILE',
+            path: manifest.destination,
+            fromGitBlob: null,
+            toGitBlob: manifest.targetGitBlob,
+            source: manifest.source
+          });
+        } catch {
+          unsafe.push({
+            owner: 'bootstrap',
+            state: 'BOOTSTRAP_MIGRATION_UNSUPPORTED',
+            path: manifest.destination,
+            detail: 'Bootstrap migration parent is missing, unsafe, or resolves outside the Project root.'
+          });
+        }
+        continue;
+      }
+      unsafe.push({
         owner: 'bootstrap',
         state: 'BOOTSTRAP_MIGRATION_UNSUPPORTED',
         path: manifest.destination,
-        detail: 'Bootstrap-generated verifier is not a regular file; refusing package mutation.'
-      }]
-    };
-  }
-  const realRoot = fs.realpathSync(consumerRoot);
-  const realDestination = fs.realpathSync(destination);
-  if (realDestination !== realRoot && !realDestination.startsWith(`${realRoot}${path.sep}`)) {
-    return {
-      rows: [],
-      unsafe: [{
+        detail: 'Bootstrap-generated file is missing; refusing package mutation before a supported migration is established.'
+      });
+      continue;
+    }
+
+    try {
+      assertSafeExistingPath(consumerRoot, destination, manifest.destination, 'file');
+    } catch (error) {
+      unsafe.push({
         owner: 'bootstrap',
         state: 'BOOTSTRAP_MIGRATION_UNSUPPORTED',
         path: manifest.destination,
-        detail: 'Bootstrap-generated verifier resolves outside the Project root; refusing package mutation.'
-      }]
-    };
-  }
+        detail: `${error.message}; refusing package mutation.`
+      });
+      continue;
+    }
 
-  const currentGitBlob = gitBlobSha(fs.readFileSync(destination));
-  if (currentGitBlob === manifest.targetGitBlob) return { rows: [], unsafe: [] };
-  if (!manifest.supportedPredecessorGitBlobs.includes(currentGitBlob)) {
-    return {
-      rows: [],
-      unsafe: [{
+    const currentGitBlob = gitBlobSha(fs.readFileSync(destination));
+    if (currentGitBlob === manifest.targetGitBlob) continue;
+    if (!manifest.supportedPredecessorGitBlobs.includes(currentGitBlob)) {
+      unsafe.push({
         owner: 'bootstrap',
         state: 'BOOTSTRAP_MIGRATION_UNSUPPORTED',
         path: manifest.destination,
-        detail: `Unknown/custom Bootstrap verifier identity ${currentGitBlob}; refusing to overwrite it.`
-      }]
-    };
-  }
+        detail: `Unknown/custom Bootstrap file identity ${currentGitBlob}; refusing to overwrite it.`
+      });
+      continue;
+    }
 
-  return {
-    rows: [{
+    rows.push({
       owner: 'bootstrap',
-      state: 'MIGRATE_BOOTSTRAP_VERIFIER',
+      state: migrationState(manifest),
       path: manifest.destination,
       fromGitBlob: currentGitBlob,
       toGitBlob: manifest.targetGitBlob,
       source: manifest.source
-    }],
-    unsafe: []
-  };
+    });
+  }
+
+  return { rows, unsafe };
 }
 
 export function applyBootstrapMigrations(packageData, migrationPlan, consumerRoot) {
   if (!migrationPlan?.rows?.length) return;
   if (migrationPlan.unsafe?.length) throw new Error('Refusing unsafe Bootstrap migration plan');
-  const { manifest, bytes } = loadManifest(packageData);
+
+  const byPath = new Map(loadManifests(packageData).map((entry) => [entry.manifest.destination, entry]));
   for (const row of migrationPlan.rows) {
-    if (row.state !== 'MIGRATE_BOOTSTRAP_VERIFIER' || row.path !== manifest.destination) {
+    const entry = byPath.get(row.path);
+    if (!entry) throw new Error(`Unsupported Bootstrap migration row path: ${row.path}`);
+    const { manifest, bytes } = entry;
+    if (!['MIGRATE_BOOTSTRAP_VERIFIER', 'MIGRATE_BOOTSTRAP_FILE', 'ADD_BOOTSTRAP_FILE'].includes(row.state)) {
       throw new Error(`Unsupported Bootstrap migration row: ${row.state ?? 'unknown'}`);
     }
+
     const destination = safeConsumerPath(consumerRoot, row.path);
-    if (!fs.existsSync(destination) || fs.lstatSync(destination).isSymbolicLink() || !fs.lstatSync(destination).isFile()) {
-      throw new Error(`Bootstrap verifier changed after preview: ${row.path}`);
-    }
-    const currentGitBlob = gitBlobSha(fs.readFileSync(destination));
-    if (currentGitBlob !== row.fromGitBlob || !manifest.supportedPredecessorGitBlobs.includes(currentGitBlob)) {
-      throw new Error(`Bootstrap verifier changed after preview: ${row.path}`);
+    if (row.state === 'ADD_BOOTSTRAP_FILE') {
+      if (!manifest.allowMissing || fs.existsSync(destination)) {
+        throw new Error(`Bootstrap file changed after preview: ${row.path}`);
+      }
+      const parent = path.dirname(destination);
+      if (!fs.existsSync(parent)) throw new Error(`Bootstrap migration parent changed after preview: ${row.path}`);
+      assertSafeExistingPath(consumerRoot, parent, path.dirname(row.path), 'directory');
+      fs.writeFileSync(destination, bytes);
+    } else {
+      if (!fs.existsSync(destination)) throw new Error(`Bootstrap file changed after preview: ${row.path}`);
+      assertSafeExistingPath(consumerRoot, destination, row.path, 'file');
+      const currentGitBlob = gitBlobSha(fs.readFileSync(destination));
+      if (currentGitBlob !== row.fromGitBlob || !manifest.supportedPredecessorGitBlobs.includes(currentGitBlob)) {
+        throw new Error(`Bootstrap file changed after preview: ${row.path}`);
+      }
+      fs.writeFileSync(destination, bytes);
     }
-    fs.writeFileSync(destination, bytes);
+
     if (gitBlobSha(fs.readFileSync(destination)) !== manifest.targetGitBlob) {
-      throw new Error(`Bootstrap verifier migration verification failed: ${row.path}`);
+      throw new Error(`Bootstrap migration verification failed: ${row.path}`);
     }
   }
 }

package/tools/windows/project-forge-wsl2.ps1

@@ -0,0 +1,265 @@
+[CmdletBinding(SupportsShouldProcess = $true)]
+param(
+    [string]$Distro = "Ubuntu",
+    [string]$SourceRoot = (Get-Location).Path,
+    [string]$DestinationRoot = "~/projects",
+    [switch]$InstallMissing,
+    [switch]$MigrateRepositories,
+    [switch]$IncludeNestedRepositories,
+    [switch]$SkipDockerCheck
+)
+
+$ErrorActionPreference = "Stop"
+
+function Write-Step([string]$Message) {
+    Write-Host "==> $Message"
+}
+
+function Invoke-Wsl {
+    param([Parameter(Mandatory = $true)][string[]]$Arguments)
+    $output = & wsl.exe -d $Distro -- @Arguments 2>&1
+    if ($LASTEXITCODE -ne 0) {
+        throw "WSL command failed ($LASTEXITCODE): $($Arguments -join ' ')`n$output"
+    }
+    return $output
+}
+
+function Test-Command([string]$Name) {
+    return $null -ne (Get-Command $Name -ErrorAction SilentlyContinue)
+}
+
+function Get-GitValue([string]$Repository, [string[]]$Arguments) {
+    $result = & git -C $Repository @Arguments 2>$null
+    if ($LASTEXITCODE -ne 0) { return $null }
+    return (($result -join "`n").Trim())
+}
+
+function Convert-ToWslPath([string]$WindowsPath) {
+    $resolved = (Resolve-Path $WindowsPath).Path
+    if ($resolved -match '^([A-Za-z]):\\(.*)$') {
+        $drive = $Matches[1].ToLowerInvariant()
+        $rest = $Matches[2] -replace '\\', '/'
+        return "/mnt/$drive/$rest"
+    }
+
+    throw "Unsupported Windows path for WSL conversion: '$resolved'. Expected a local drive-letter path such as C:\\Projects\\repo."
+}
+
+function Resolve-WslDestinationRoot {
+    if ($DestinationRoot.StartsWith("/")) { return $DestinationRoot }
+
+    $wslHome = ((Invoke-Wsl -Arguments @("sh", "-lc", 'printf %s "$HOME"')) -join "`n").Trim()
+    if (-not $wslHome) {
+        throw "Could not resolve the WSL home directory for '$Distro'. Supply -DestinationRoot with an absolute Linux path such as /home/<user>/projects."
+    }
+
+    if ($DestinationRoot -eq "~") { return $wslHome }
+    if ($DestinationRoot.StartsWith("~/")) {
+        return "$wslHome/$($DestinationRoot.Substring(2))"
+    }
+    throw "DestinationRoot must be an absolute Linux path or start with ~/ (received '$DestinationRoot')."
+}
+
+function Get-RepositoryCandidates([string]$Root) {
+    $resolved = (Resolve-Path $Root).Path
+    $items = New-Object System.Collections.Generic.List[string]
+
+    if (Test-Path (Join-Path $resolved ".git")) {
+        $items.Add($resolved)
+    }
+
+    $children = Get-ChildItem -Path $resolved -Directory -Force
+    foreach ($child in $children) {
+        if (Test-Path (Join-Path $child.FullName ".git")) {
+            $items.Add($child.FullName)
+        }
+    }
+
+    if ($IncludeNestedRepositories) {
+        Get-ChildItem -Path $resolved -Directory -Force -Recurse -ErrorAction SilentlyContinue |
+            Where-Object { Test-Path (Join-Path $_.FullName ".git") } |
+            ForEach-Object { $items.Add($_.FullName) }
+    }
+
+    return $items | Sort-Object -Unique
+}
+
+if (-not [System.Environment]::OSVersion.Platform.ToString().StartsWith("Win")) {
+    throw "This tool must be run from Windows PowerShell or PowerShell on Windows."
+}
+
+Write-Step "Checking WSL2"
+if (-not (Test-Command "wsl.exe")) {
+    if (-not $InstallMissing) {
+        throw "WSL is not available. Re-run with -InstallMissing from an elevated PowerShell session."
+    }
+    & wsl.exe --install -d $Distro
+    throw "WSL installation was requested. If Windows asks for a restart, restart first, complete the $Distro first-run setup, then run this command again."
+}
+
+& wsl.exe --set-default-version 2 | Out-Null
+$distroNames = (& wsl.exe -l -q 2>$null) -replace "`0", "" | ForEach-Object { $_.Trim() } | Where-Object { $_ }
+if ($distroNames -notcontains $Distro) {
+    if (-not $InstallMissing) {
+        throw "WSL distro '$Distro' is not installed. Re-run with -InstallMissing."
+    }
+    & wsl.exe --install -d $Distro
+    throw "Installation of '$Distro' was requested. Complete its first-run setup, then run this command again."
+}
+
+$versionLines = (& wsl.exe -l -v 2>$null) -replace "`0", ""
+$distroLine = $versionLines | Where-Object { $_ -match "\b$([regex]::Escape($Distro))\b" } | Select-Object -First 1
+if ($distroLine -and $distroLine -match "\s1\s*$") {
+    if (-not $InstallMissing) {
+        throw "'$Distro' is using WSL1. Re-run with -InstallMissing to convert it to WSL2."
+    }
+    & wsl.exe --set-version $Distro 2
+    if ($LASTEXITCODE -ne 0) { throw "Failed to convert '$Distro' to WSL2." }
+}
+
+Write-Step "Checking baseline Linux development tools"
+$missingLinuxTools = @()
+foreach ($tool in @("git", "curl", "tar")) {
+    & wsl.exe -d $Distro -- sh -lc "command -v $tool >/dev/null 2>&1"
+    if ($LASTEXITCODE -ne 0) { $missingLinuxTools += $tool }
+}
+if ($missingLinuxTools.Count -gt 0) {
+    if (-not $InstallMissing) {
+        throw "Missing WSL tools: $($missingLinuxTools -join ', '). Re-run with -InstallMissing."
+    }
+    Invoke-Wsl -Arguments @("sudo", "apt-get", "update") | Out-Null
+    Invoke-Wsl -Arguments @("sudo", "apt-get", "install", "-y", "git", "curl", "ca-certificates", "tar", "build-essential") | Out-Null
+}
+
+# Use Linux line endings for new checkouts unless the Builder already chose another global policy.
+$wslAutocrlf = (& wsl.exe -d $Distro -- git config --global --get core.autocrlf 2>$null | Out-String).Trim()
+if (-not $wslAutocrlf) {
+    Invoke-Wsl -Arguments @("git", "config", "--global", "core.autocrlf", "input") | Out-Null
+}
+
+# Carry Git identity into WSL only when WSL does not already have one.
+if (Test-Command "git") {
+    foreach ($key in @("user.name", "user.email")) {
+        $existing = (& wsl.exe -d $Distro -- git config --global --get $key 2>$null | Out-String).Trim()
+        if (-not $existing) {
+            $hostValue = (& git config --global --get $key 2>$null | Out-String).Trim()
+            if ($hostValue) { Invoke-Wsl -Arguments @("git", "config", "--global", $key, $hostValue) | Out-Null }
+        }
+    }
+}
+
+Write-Step "Checking VS Code WSL integration"
+if (Test-Command "code") {
+    & code --install-extension ms-vscode-remote.remote-wsl --force | Out-Null
+} else {
+    Write-Warning "VS Code 'code' command was not found on Windows. Install VS Code if you want the recommended Windows UI + WSL workspace flow."
+}
+
+Write-Step "Checking Docker Desktop / WSL integration"
+if (-not $SkipDockerCheck) {
+    $dockerDesktop = Get-Command "docker" -ErrorAction SilentlyContinue
+    if (-not $dockerDesktop -and $InstallMissing -and (Test-Command "winget")) {
+        & winget install --id Docker.DockerDesktop -e --accept-package-agreements --accept-source-agreements
+        Write-Warning "Docker Desktop installation was requested. Start Docker Desktop, enable WSL integration for '$Distro', then rerun this command to verify Docker from WSL."
+    }
+
+    & wsl.exe -d $Distro -- docker info 1>$null 2>$null
+    if ($LASTEXITCODE -ne 0) {
+        Write-Warning "Docker is not operational inside '$Distro'. Start Docker Desktop and enable Settings > Resources > WSL Integration for '$Distro'. Do not install a second Docker Engine inside WSL just to satisfy this check."
+    } else {
+        Write-Host "Docker from WSL: PASS"
+    }
+}
+
+if (-not $MigrateRepositories) {
+    Write-Host ""
+    Write-Host "WSL2 baseline setup: PASS"
+    Write-Host "No repositories were migrated. Re-run with -MigrateRepositories -SourceRoot <windows-folder> when ready."
+    exit 0
+}
+
+if (-not (Test-Command "git")) {
+    throw "Windows Git is required for migration preflight so source repositories can be verified before copying state."
+}
+
+$destinationRootLinux = Resolve-WslDestinationRoot
+Invoke-Wsl -Arguments @("mkdir", "-p", $destinationRootLinux) | Out-Null
+$repositories = @(Get-RepositoryCandidates $SourceRoot)
+if ($repositories.Count -eq 0) {
+    throw "No Git repositories found at '$SourceRoot'."
+}
+
+Write-Step "Migrating $($repositories.Count) repository/repositories to ${Distro}:$destinationRootLinux"
+$migrated = New-Object System.Collections.Generic.List[string]
+$skipped = New-Object System.Collections.Generic.List[string]
+
+foreach ($repo in $repositories) {
+    $name = Split-Path $repo -Leaf
+    $dirty = (& git -C $repo status --porcelain=v1 2>$null | Out-String).Trim()
+    if ($LASTEXITCODE -ne 0) {
+        Write-Warning "Skipping '$repo': Git status failed."
+        $skipped.Add($repo)
+        continue
+    }
+    if ($dirty) {
+        Write-Warning "Skipping '$repo': working tree is not clean. Commit/stash/reconcile it first so migration cannot lose local work."
+        $skipped.Add($repo)
+        continue
+    }
+
+    $head = Get-GitValue $repo @("rev-parse", "HEAD")
+    $branch = Get-GitValue $repo @("branch", "--show-current")
+    $origin = Get-GitValue $repo @("config", "--get", "remote.origin.url")
+    $sourceLinux = Convert-ToWslPath $repo
+    $destinationLinux = "$destinationRootLinux/$name"
+
+    & wsl.exe -d $Distro -- test -e $destinationLinux
+    if ($LASTEXITCODE -eq 0) {
+        Write-Warning "Skipping '$repo': destination '$destinationLinux' already exists."
+        $skipped.Add($repo)
+        continue
+    }
+
+    if (-not $PSCmdlet.ShouldProcess($repo, "Create validated WSL2 checkout at $destinationLinux")) {
+        continue
+    }
+
+    # Clone from the local clean repository so committed local-only refs remain available during migration.
+    Invoke-Wsl -Arguments @("git", "clone", "--no-hardlinks", $sourceLinux, $destinationLinux) | Out-Null
+    if ($origin) {
+        Invoke-Wsl -Arguments @("git", "-C", $destinationLinux, "remote", "set-url", "origin", $origin) | Out-Null
+    }
+
+    $destHead = ((Invoke-Wsl -Arguments @("git", "-C", $destinationLinux, "rev-parse", "HEAD")) -join "`n").Trim()
+    $destDirty = ((Invoke-Wsl -Arguments @("git", "-C", $destinationLinux, "status", "--porcelain=v1")) -join "`n").Trim()
+    if ($destHead -ne $head) {
+        throw "Migration verification failed for '$name': source HEAD $head != destination HEAD $destHead. Windows source was left untouched."
+    }
+    if ($destDirty) {
+        throw "Migration verification failed for '$name': destination checkout is not clean. Windows source was left untouched."
+    }
+
+    if ($branch) {
+        $destBranch = ((Invoke-Wsl -Arguments @("git", "-C", $destinationLinux, "branch", "--show-current")) -join "`n").Trim()
+        if ($destBranch -ne $branch) {
+            Write-Warning "'$name' migrated at the correct HEAD, but checked-out branch differs (source '$branch', destination '$destBranch')."
+        }
+    }
+
+    Write-Host "Migrated: $repo -> ${Distro}:$destinationLinux"
+    $migrated.Add($destinationLinux)
+}
+
+Write-Host ""
+Write-Host "Migration complete."
+Write-Host "Migrated: $($migrated.Count)"
+Write-Host "Skipped:  $($skipped.Count)"
+Write-Host "Windows source checkouts were NOT deleted."
+Write-Host ""
+Write-Host "Next: open a migrated repository from WSL and run its normal Project Forge/project readiness checks."
+if ($migrated.Count -gt 0) {
+    Write-Host "Example:"
+    Write-Host "  wsl -d $Distro"
+    Write-Host "  cd $($migrated[0])"
+    Write-Host "  code ."
+}