@mriekki/project-forge 4.13.4 → 4.14.0

package/README.md

@@ -8,13 +8,13 @@ The Builder brings the idea and makes the material decisions. Project Forge supp
 
 ## What it feels like
 
-Start with an idea:
+Start with the one Project-creation prompt:
 
 ```text
-New Project: I want to build a hiking trail tracker.
+New Project
 ```
 
-Project Forge guides the Builder through:
+Project Forge presents the currently supported ways to begin, explains each option, and then guides the Builder through the path they select. A greenfield path looks like:
 
 ```text
 idea
@@ -72,7 +72,8 @@ open personal invitation
 → accept invitation
 → automatic readiness verification
 → configure one ChatGPT coding Project
-→ New Project: <idea>
+→ New Project
+→ choose a supported start mode
 ```
 
 **Project Forge Builder** is the GitHub App used for Project Forge authorization and project orchestration.
@@ -93,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/components.json

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

package/assets/generated/ASSEMBLY.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.13.4",
+  "version": "4.14.0",
   "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/tools/windows/project-forge-wsl2.ps1

@@ -0,0 +1,253 @@
+[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(ValueFromRemainingArguments = $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) {
+    return ((Invoke-Wsl wslpath -a $WindowsPath) -join "`n").Trim()
+}
+
+function Resolve-WslDestinationRoot {
+    $home = ((Invoke-Wsl sh -lc 'printf %s "$HOME"') -join "`n").Trim()
+    if ($DestinationRoot -eq "~") { return $home }
+    if ($DestinationRoot.StartsWith("~/")) {
+        return "$home/$($DestinationRoot.Substring(2))"
+    }
+    if ($DestinationRoot.StartsWith("/")) { return $DestinationRoot }
+    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 sudo apt-get update | Out-Null
+    Invoke-Wsl 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
+}
+
+# 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 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 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 git clone --no-hardlinks $sourceLinux $destinationLinux | Out-Null
+    if ($origin) {
+        Invoke-Wsl 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()
+    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 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 ."
+}