@mriekki/project-forge 4.14.0 → 4.14.2

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,21 @@
+{
+  "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": "9f0f7fd4e0e2220250f6fd5b035706a7d15834af",
+    "artifact": "runtime/dev_environment_wsl.py"
+  },
+  "targetGitBlob": "883f7bbadd2de4bc0dcb601ee2285f88a0085b52",
+  "supportedPredecessorGitBlobs": [
+    "6731910246fb99887c58b9f3a8a14fec1bf02c01"
+  ],
+  "supportedBootstrapRevisions": [
+    "0c45eb332a815ad79ea061443f337500b9dc5712",
+    "173203baaf36935d04eb81c89f1d016131a40442"
+  ],
+  "allowMissing": true
+}

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

@@ -0,0 +1,328 @@
+#!/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 fnm_install_dir() -> Path:
+    xdg_data_home = os.environ.get("XDG_DATA_HOME")
+    base = Path(xdg_data_home).expanduser() if xdg_data_home else Path.home() / ".local" / "share"
+    return base / "fnm"
+
+
+def refresh_fnm_path() -> None:
+    install_dir = fnm_install_dir()
+    fnm_binary = install_dir / "fnm"
+    if not fnm_binary.is_file():
+        return
+    current = os.environ.get("PATH", "")
+    prefix = str(install_dir)
+    parts = current.split(os.pathsep) if current else []
+    if prefix not in parts:
+        os.environ["PATH"] = prefix + (os.pathsep + current if current else "")
+
+
+def ensure_fnm_available(check_only: bool) -> tuple[bool, str, str]:
+    refresh_fnm_path()
+    path = command_path("fnm")
+    if path:
+        result = run(["fnm", "--version"])
+        detail = "\n".join(filter(None, [(result.stdout or "").strip(), (result.stderr or "").strip()]))
+        return result.returncode == 0, detail or path, "PASS" if result.returncode == 0 else "FAILED"
+
+    if check_only:
+        return False, "fnm is missing in WSL", "MISSING"
+
+    ensure_apt_package("curl")
+    ensure_apt_package("unzip")
+    install = run(
+        ["bash", "-lc", "curl -fsSL https://fnm.vercel.app/install | bash"],
+        capture=False,
+    )
+    if install.returncode != 0:
+        return False, "fnm installer failed", "FAILED"
+
+    refresh_fnm_path()
+    path = command_path("fnm")
+    if not path:
+        return False, f"fnm installer completed but {fnm_install_dir() / 'fnm'} is unavailable", "FAILED"
+
+    verify = run(["fnm", "--version"])
+    detail = "\n".join(filter(None, [(verify.stdout or "").strip(), (verify.stderr or "").strip()]))
+    return verify.returncode == 0, detail or path, "PASS" if verify.returncode == 0 else "FAILED"
+
+
+def ensure_fnm_node(version: str | None, check_only: bool) -> tuple[bool, str, str]:
+    fnm_ok, fnm_detail, fnm_state = ensure_fnm_available(check_only)
+    if not fnm_ok:
+        return False, fnm_detail, fnm_state
+    if not version:
+        return True, fnm_detail or "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"
+    default = run(["fnm", "default", version], capture=False)
+    if default.returncode != 0:
+        return False, f"fnm installed Node {version} but failed to make it the default", "FAILED"
+
+    verify = run(["fnm", "exec", f"--using={version}", "--", "node", "--version"])
+    text = (verify.stdout or verify.stderr or "").strip()
+    ok = verify.returncode == 0 and version in text.lstrip("v")
+    return ok, text or f"Node {version} verification failed", "PASS" if ok 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 == "fnm":
+        return ensure_fnm_available(check_only)
+    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"
+
+    if tool_id == "python":
+        ensure_apt_package("python3")
+        ensure_apt_package("python-is-python3")
+        ok, detail = version_ok(spec, version)
+        return ok, detail, "PASS" if ok else "FAILED"
+
+    apt_packages = {
+        "git": "git",
+        "github-cli": "gh",
+        "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 == "dotnet":
+        if not version:
+            return False, ".NET SDK version is required for automatic WSL installation", "FAILED"
+        major = version.split(".", 1)[0]
+        if not re.fullmatch(r"\d+", major):
+            return False, f"Unsupported .NET SDK version: {version}", "FAILED"
+        ensure_apt_package(f"dotnet-sdk-{major}.0")
+        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 == "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.14.0",
+  "version": "4.14.2",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {

package/assets/generated/ASSEMBLY.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.14.0",
+  "version": "4.14.2",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {

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

@@ -16,7 +16,7 @@ function Write-Step([string]$Message) {
 }
 
 function Invoke-Wsl {
-    param([Parameter(ValueFromRemainingArguments = $true)][string[]]$Arguments)
+    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"
@@ -35,16 +35,28 @@ function Get-GitValue([string]$Repository, [string[]]$Arguments) {
 }
 
 function Convert-ToWslPath([string]$WindowsPath) {
-    return ((Invoke-Wsl wslpath -a $WindowsPath) -join "`n").Trim()
+    $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 {
-    $home = ((Invoke-Wsl sh -lc 'printf %s "$HOME"') -join "`n").Trim()
-    if ($DestinationRoot -eq "~") { return $home }
+    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 "$home/$($DestinationRoot.Substring(2))"
+        return "$wslHome/$($DestinationRoot.Substring(2))"
     }
-    if ($DestinationRoot.StartsWith("/")) { return $DestinationRoot }
     throw "DestinationRoot must be an absolute Linux path or start with ~/ (received '$DestinationRoot')."
 }
 
@@ -115,14 +127,14 @@ if ($missingLinuxTools.Count -gt 0) {
     if (-not $InstallMissing) {
         throw "Missing WSL tools: $($missingLinuxTools -join ', '). Re-run with -InstallMissing."
     }
-    Invoke-Wsl sudo apt-get update | Out-Null
-    Invoke-Wsl sudo apt-get install -y git curl ca-certificates tar build-essential | Out-Null
+    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 git config --global core.autocrlf input | Out-Null
+    Invoke-Wsl -Arguments @("git", "config", "--global", "core.autocrlf", "input") | Out-Null
 }
 
 # Carry Git identity into WSL only when WSL does not already have one.
@@ -131,7 +143,7 @@ if (Test-Command "git") {
         $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 git config --global $key $hostValue | Out-Null }
+            if ($hostValue) { Invoke-Wsl -Arguments @("git", "config", "--global", $key, $hostValue) | Out-Null }
         }
     }
 }
@@ -171,13 +183,13 @@ if (-not (Test-Command "git")) {
 }
 
 $destinationRootLinux = Resolve-WslDestinationRoot
-Invoke-Wsl mkdir -p $destinationRootLinux | Out-Null
+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"
+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]
 
@@ -213,13 +225,13 @@ foreach ($repo in $repositories) {
     }
 
     # Clone from the local clean repository so committed local-only refs remain available during migration.
-    Invoke-Wsl git clone --no-hardlinks $sourceLinux $destinationLinux | Out-Null
+    Invoke-Wsl -Arguments @("git", "clone", "--no-hardlinks", $sourceLinux, $destinationLinux) | Out-Null
     if ($origin) {
-        Invoke-Wsl git -C $destinationLinux remote set-url origin $origin | Out-Null
+        Invoke-Wsl -Arguments @("git", "-C", $destinationLinux, "remote", "set-url", "origin", $origin) | Out-Null
     }
 
-    $destHead = ((Invoke-Wsl git -C $destinationLinux rev-parse HEAD) -join "`n").Trim()
-    $destDirty = ((Invoke-Wsl git -C $destinationLinux status --porcelain=v1) -join "`n").Trim()
+    $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."
     }
@@ -228,13 +240,13 @@ foreach ($repo in $repositories) {
     }
 
     if ($branch) {
-        $destBranch = ((Invoke-Wsl git -C $destinationLinux branch --show-current) -join "`n").Trim()
+        $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"
+    Write-Host "Migrated: $repo -> ${Distro}:$destinationLinux"
     $migrated.Add($destinationLinux)
 }