@caddis/cli 0.4.19 → 0.4.21

package/bundles/antigravity-plugin/skills/port-to-github/scripts/PortCommon.ps1

@@ -0,0 +1,130 @@
+# Shared helpers for the port-to-github scripts. Dot-source this file.
+# ASCII only: these scripts may be read by Windows PowerShell 5.1.
+
+Set-StrictMode -Version 2.0
+
+function Write-PortStep([string]$Message) {
+    Write-Host "==> $Message" -ForegroundColor Cyan
+}
+
+function Write-PortWarn([string]$Message) {
+    Write-Host "[WARN] $Message" -ForegroundColor Yellow
+}
+
+function Write-PortFail([string]$Message) {
+    Write-Host "[FAIL] $Message" -ForegroundColor Red
+}
+
+function Write-PortOk([string]$Message) {
+    Write-Host "[OK] $Message" -ForegroundColor Green
+}
+
+# Run git and fail loud on a non-zero exit. Returns stdout lines.
+# safe.directory=* lets us READ a repository another account owns (a UNC share,
+# a service-owned prod checkout). -c is forwarded to git's subprocesses through
+# GIT_CONFIG_PARAMETERS, so upload-pack sees it too.
+function Invoke-PortGit {
+    param(
+        [Parameter(Mandatory)][string[]]$Arguments,
+        [switch]$AllowFailure
+    )
+    $all = @('-c', 'safe.directory=*') + $Arguments
+    $out = & git @all 2>&1
+    $code = $LASTEXITCODE
+    $text = @($out | ForEach-Object { "$_" })
+    if ($code -ne 0 -and -not $AllowFailure) {
+        throw "git $($Arguments -join ' ') failed with exit $code`n$($text -join "`n")"
+    }
+    if ($AllowFailure) {
+        return [pscustomobject]@{ ExitCode = $code; Output = $text }
+    }
+    return $text
+}
+
+# Read defaults from a project config file. Order: -ConfigPath, $env:PORT_TO_GITHUB_CONFIG,
+# .caddis/port-to-github.json in the current git repository. Missing file = empty config.
+function Get-PortConfig([string]$ConfigPath) {
+    $candidates = @()
+    if ($ConfigPath) { $candidates += $ConfigPath }
+    if ($env:PORT_TO_GITHUB_CONFIG) { $candidates += $env:PORT_TO_GITHUB_CONFIG }
+    $top = & git rev-parse --show-toplevel 2>$null
+    if ($LASTEXITCODE -eq 0 -and $top) {
+        $candidates += (Join-Path $top '.caddis/port-to-github.json')
+    }
+    foreach ($c in $candidates) {
+        if ($c -and (Test-Path -LiteralPath $c)) {
+            $cfg = Get-Content -LiteralPath $c -Raw | ConvertFrom-Json
+            $cfg | Add-Member -NotePropertyName _path -NotePropertyValue (Resolve-Path -LiteralPath $c).Path -Force
+            return $cfg
+        }
+    }
+    return [pscustomobject]@{ _path = $null }
+}
+
+function Get-PortConfigValue($Config, [string]$Name, $Default) {
+    if ($null -ne $Config -and $Config.PSObject.Properties.Name -contains $Name -and $null -ne $Config.$Name -and "$($Config.$Name)" -ne '') {
+        return $Config.$Name
+    }
+    return $Default
+}
+
+function Get-PortStagingRoot($Config, [string]$Override) {
+    if ($Override) { $root = $Override }
+    else { $root = Get-PortConfigValue $Config 'stagingRoot' (Join-Path ([IO.Path]::GetTempPath()) 'port-to-github') }
+    $root = [Environment]::ExpandEnvironmentVariables($root)
+    New-Item -ItemType Directory -Force -Path $root | Out-Null
+    return (Resolve-Path -LiteralPath $root).Path
+}
+
+# Remove "user:secret@" from a URL. Returns @{ Url; HadCredential }.
+function Remove-UrlCredential([string]$Url) {
+    if ($Url -match '^(?<scheme>[a-zA-Z][a-zA-Z0-9+.-]*://)(?<userinfo>[^@/]+)@(?<rest>.*)$') {
+        return [pscustomobject]@{ Url = "$($Matches.scheme)$($Matches.rest)"; HadCredential = ($Matches.userinfo -match ':') }
+    }
+    return [pscustomobject]@{ Url = $Url; HadCredential = $false }
+}
+
+# Directories that are never source, skipped when importing a plain folder (no .git).
+# Only unambiguous ones: 'dist', 'build', 'bin' can hold real source in some projects,
+# so they are imported and REPORTED instead (see $PortSuspectDirs).
+$script:PortJunkDirs = @(
+    'node_modules', '.venv', 'venv', '__pycache__', '.pytest_cache', '.mypy_cache',
+    '.ruff_cache', '.tox', '.next', '.nuxt', '.parcel-cache', '.turbo', 'htmlcov', '.git'
+)
+$script:PortSuspectDirs = @('dist', 'build', 'bin', 'obj', 'out', 'coverage', 'logs', 'data')
+
+# File-name patterns that usually hold secrets.
+$script:PortSecretNamePatterns = @(
+    '^\.env$', '^\.env\..+', '\.pem$', '\.key$', '\.pfx$', '\.p12$', '^id_rsa', '^id_ed25519',
+    '^credentials(\..+)?$', '\.kdbx$', '^\.netrc$', '^\.git-credentials$', '^\.npmrc$', '^\.pypirc$'
+)
+# .env.example / .env.sample / .env.template are documentation, not secrets.
+$script:PortSecretNameAllow = @('\.example$', '\.sample$', '\.template$', '\.dist$')
+
+# Content patterns that usually are a real credential.
+$script:PortSecretContentPatterns = @(
+    'gh[pousr]_[A-Za-z0-9]{36,}',
+    'github_pat_[A-Za-z0-9_]{40,}',
+    'AKIA[0-9A-Z]{16}',
+    '-----BEGIN [A-Z ]*PRIVATE KEY-----',
+    'xox[baprs]-[A-Za-z0-9-]{10,}',
+    '(?i)(password|passwd|pwd|secret|api[_-]?key|token)\s*[:=]\s*[''"][^''"\s]{8,}[''"]',
+    '(?i)(password|pwd)=[^;\s]{6,};'
+)
+
+function Test-PortSecretName([string]$FileName) {
+    foreach ($a in $script:PortSecretNameAllow) { if ($FileName -match $a) { return $false } }
+    foreach ($p in $script:PortSecretNamePatterns) { if ($FileName -match $p) { return $true } }
+    return $false
+}
+
+function Test-PortSecretContent([string]$Text) {
+    foreach ($p in $script:PortSecretContentPatterns) {
+        if ($Text -match $p) { return $p }
+    }
+    return $null
+}
+
+function ConvertTo-PortJsonFile($Object, [string]$Path) {
+    $Object | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $Path -Encoding UTF8
+}

package/bundles/antigravity-plugin/skills/port-to-github/scripts/Publish-PortToGitHub.ps1

@@ -0,0 +1,156 @@
+<#
+.SYNOPSIS
+  Create the GitHub repository (empty) and push a staged mirror to it, then prove every ref landed.
+
+.DESCRIPTION
+  - Pushes with an EXPLICIT refspec (heads and tags). Never --mirror: a server's hidden refs
+    (refs/pull/*) are refused by GitHub, and --mirror would also DELETE anything on GitHub the
+    stage lacks.
+  - Never force-pushes. If the GitHub repo already exists it must be empty, or every one of its
+    branches must be an ancestor of (or equal to) the staged branch of the same name. Otherwise it
+    refuses: pushing on top of unrelated history welds a fake ancestry in permanently.
+  - Verifies by SHA with Compare-PortRefs.ps1 and exits 1 if any ref differs.
+
+  Uses the gh CLI for the API and your normal git credential helper for the push
+  (run `gh auth setup-git` once if git cannot authenticate to github.com).
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [Parameter(Mandatory)][string]$Name,
+    [string]$Owner,
+    [string]$Repo,
+    [ValidateSet('private', 'internal', 'public')][string]$Visibility,
+    [string]$Description,
+    [string]$StagingRoot,
+    [string]$ConfigPath,
+    # Allow pushing into an existing NON-empty repo whose history is compatible (fast-forward only).
+    [switch]$AllowExisting,
+    # The staged branches already contain .github/workflows; pushing them WILL run those
+    # workflows (a deploy job included). Pass only after reading them.
+    [switch]$AllowWorkflowRuns
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'PortCommon.ps1')
+
+$config = Get-PortConfig $ConfigPath
+$stage = Join-Path (Get-PortStagingRoot $config $StagingRoot) $Name
+$mirror = Join-Path $stage 'mirror.git'
+$manifestPath = Join-Path $stage 'manifest.json'
+if (-not (Test-Path -LiteralPath $mirror)) { throw "No staged mirror at $mirror. Run Get-PortSource.ps1 first." }
+$manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json
+
+$readinessPath = Join-Path $stage 'readiness.json'
+if (-not (Test-Path -LiteralPath $readinessPath)) { throw "No readiness report. Run Test-PortReadiness.ps1 -Name $Name first." }
+$readiness = Get-Content -LiteralPath $readinessPath -Raw | ConvertFrom-Json
+if (-not $readiness.ready) { throw "Readiness has $(@($readiness.blockers).Count) blocker(s). Fix them and re-run Test-PortReadiness.ps1 before publishing." }
+$live = @()
+if ($readiness.PSObject.Properties.Name -contains 'branchesWithGithubWorkflows') { $live = @($readiness.branchesWithGithubWorkflows) }
+if ($live.Count -gt 0 -and -not $AllowWorkflowRuns) {
+    throw "Branch(es) $($live -join ', ') contain .github/workflows. The push will RUN them on GitHub (deploy jobs included). Read them, then re-run with -AllowWorkflowRuns - or remove/disable them in the source first."
+}
+
+# The stage must still hold exactly what Get-PortSource recorded. Anything else (a stray fetch,
+# a hand edit, a second tool) would be pushed and then "verified" against itself.
+$nowRefs = @(Invoke-PortGit @('-C', $mirror, 'for-each-ref', '--format=%(refname:short) %(objectname)', 'refs/heads', 'refs/tags') | Sort-Object)
+$wasRefs = @(@($manifest.heads) + @($manifest.tags) | Where-Object { $_ } | Sort-Object)
+$drift = @(Compare-Object $wasRefs $nowRefs)
+$extra = @(Invoke-PortGit @('-C', $mirror, 'for-each-ref', '--format=%(refname)') | Where-Object { $_ -and $_ -notlike 'refs/heads/*' -and $_ -notlike 'refs/tags/*' })
+if ($drift.Count -gt 0 -or $extra.Count -gt 0) {
+    $d = @($drift | ForEach-Object { "$($_.SideIndicator) $($_.InputObject)" }) + @($extra | ForEach-Object { "extra $_" })
+    throw "The staged mirror no longer matches manifest.json (=> added, <= missing):`n  $($d -join "`n  ")`nRe-run Get-PortSource.ps1 -Force to rebuild the stage."
+}
+
+if (-not $Owner) { $Owner = Get-PortConfigValue $config 'owner' $null }
+if (-not $Owner) { throw 'No -Owner and no "owner" in the config file.' }
+if (-not $Repo) { $Repo = $Name }
+if (-not $Visibility) { $Visibility = Get-PortConfigValue $config 'visibility' 'private' }
+$full = "$Owner/$Repo"
+$url = "https://github.com/$full.git"
+
+# ---- 1. Who am I, and can I see the owner -------------------------------------------------------
+$login = (& gh api user --jq .login 2>&1)
+if ($LASTEXITCODE -ne 0) { throw "gh is not signed in: $login. Run gh auth login." }
+Write-PortStep "Signed in to GitHub as $login; target $full ($Visibility)"
+
+# ---- 2. Does the repo exist? -----------------------------------------------------------------------
+$exists = $false
+$null = & gh api "repos/$full" --jq .full_name 2>$null
+if ($LASTEXITCODE -eq 0) { $exists = $true }
+$global:LASTEXITCODE = 0
+
+if ($exists) {
+    $remoteRefs = @(Invoke-PortGit @('ls-remote', '--heads', $url))
+    if ($remoteRefs.Count -eq 0 -or -not ($remoteRefs -join '')) {
+        Write-PortStep "$full exists and is empty. Using it."
+    }
+    else {
+        if (-not $AllowExisting) {
+            throw "$full already exists and has $($remoteRefs.Count) branch(es). Check it shares history with the source (see SKILL.md, 'An existing repo'), then re-run with -AllowExisting, or delete it and re-run."
+        }
+        Write-PortStep "$full exists with history. Checking every GitHub branch is an ancestor of the staged branch."
+        # --no-tags: without it git auto-follows the OTHER repo's tags into the stage, and the
+        # next push would publish them. Found by the dogfood run, 2026-09-19.
+        Invoke-PortGit @('-C', $mirror, 'fetch', '-q', '--no-tags', $url, '+refs/heads/*:refs/port-check/*') | Out-Null
+        try {
+            foreach ($line in $remoteRefs) {
+                $sha, $ref = $line -split "`t", 2
+                $b = $ref.Substring(11)
+                $local = Invoke-PortGit -AllowFailure @('-C', $mirror, 'rev-parse', '--verify', '-q', "refs/heads/$b")
+                if ($local.ExitCode -ne 0) { continue }   # branch only on GitHub: left alone
+                $anc = Invoke-PortGit -AllowFailure @('-C', $mirror, 'merge-base', '--is-ancestor', $sha, ($local.Output -join ''))
+                if ($anc.ExitCode -ne 0) {
+                    throw "GitHub branch '$b' ($($sha.Substring(0,12))) is NOT an ancestor of the staged '$b'. The histories are unrelated or diverged. Refusing: resolve this by hand."
+                }
+            }
+        }
+        finally {
+            foreach ($r in @(Invoke-PortGit @('-C', $mirror, 'for-each-ref', '--format=%(refname)', 'refs/port-check'))) {
+                if ($r) { Invoke-PortGit @('-C', $mirror, 'update-ref', '-d', $r) | Out-Null }
+            }
+        }
+        Write-PortOk 'Every GitHub branch is an ancestor. The push is a fast-forward.'
+    }
+}
+else {
+    if ($PSCmdlet.ShouldProcess($full, "Create $Visibility GitHub repository")) {
+        $createArgs = @('repo', 'create', $full, "--$Visibility", '--disable-wiki')
+        if ($Description) { $createArgs += @('--description', $Description) }
+        $out = & gh @createArgs 2>&1
+        if ($LASTEXITCODE -ne 0) { throw "gh repo create failed: $out" }
+        Write-PortOk "Created $full"
+    }
+    else { Write-Host "WhatIf: would create $full"; return }
+}
+
+# ---- 3. Push -------------------------------------------------------------------------------------------
+if ($PSCmdlet.ShouldProcess($full, 'Push refs/heads/* and refs/tags/*')) {
+    Write-PortStep "Pushing branches and tags to $full"
+    # --no-verify is NOT used: no hooks exist in a fresh bare mirror anyway.
+    Invoke-PortGit @('-C', $mirror, 'push', '--porcelain', $url, 'refs/heads/*:refs/heads/*', 'refs/tags/*:refs/tags/*') | Out-Null
+}
+else { Write-Host "WhatIf: would push to $url"; return }
+
+# ---- 4. Default branch ---------------------------------------------------------------------------------
+$def = $manifest.defaultBranch
+$cur = (& gh api "repos/$full" --jq .default_branch 2>$null)
+if ($cur -ne $def) {
+    & gh api -X PATCH "repos/$full" -f "default_branch=$def" --silent 2>&1 | Out-Null
+    if ($LASTEXITCODE -ne 0) { Write-PortWarn "Could not set the default branch to $def. Set it by hand." }
+}
+
+# ---- 5. Prove it by SHA ---------------------------------------------------------------------------------
+Write-PortStep 'Verifying every branch and tag by SHA'
+$mode = if ($exists) { 'LeftInRight' } else { 'Equal' }
+& (Join-Path $PSScriptRoot 'Compare-PortRefs.ps1') -Left $mirror -Right $url -Mode $mode -LeftLabel 'staged' -RightLabel 'github'
+$verified = ($LASTEXITCODE -eq 0)
+
+$manifest | Add-Member -NotePropertyName github -NotePropertyValue ([pscustomobject]@{
+        repo = $full; url = $url; pushedAt = (Get-Date).ToString('o'); pushedBy = $login; verified = $verified; defaultBranch = $def
+    }) -Force
+$manifest.status = if ($verified) { 'published' } else { 'publish-unverified' }
+ConvertTo-PortJsonFile $manifest $manifestPath
+
+if (-not $verified) { Write-PortFail "Push finished but refs do not match. Do NOT continue to CI or cutover."; exit 1 }
+Write-PortOk "Published $full - https://github.com/$full"
+exit 0

package/bundles/antigravity-plugin/skills/port-to-github/scripts/Switch-CheckoutOrigin.ps1

@@ -0,0 +1,182 @@
+<#
+.SYNOPSIS
+  Repoint an existing checkout (a deploy target, a dev box) from its old origin to GitHub,
+  prove it still agrees with GitHub, and roll back by itself if it does not.
+
+.DESCRIPTION
+  Works on a local path, or on a remote box over WinRM (-ComputerName).
+
+  -Mode Inspect   print origin, branch, HEAD, dirty count. Changes nothing.
+  -Mode Switch    record the old URL in a local state file, keep it as a second remote
+                  (-KeepOldAs), set origin to -NewUrl, fetch, and require HEAD to be contained
+                  in some origin/* branch. On ANY failure the old URL is restored at once.
+  -Mode Rollback  put the old URL back from the state file and remove the remote Switch added.
+
+  A deploy host usually holds NO GitHub credential of its own: CI supplies one per run.
+  -VerifyWithGhToken passes your current gh token to that ONE fetch as an HTTP header in the
+  process environment. It is never written to disk or to git config, and it is gone when the
+  command ends. Without it, a private repo fetch on such a host fails and the switch rolls back.
+
+  If the old URL embedded a credential (user:secret@host), the state file stores it WITHOUT
+  the credential and says so. Rotate that credential.
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [Parameter(Mandatory)][string]$Path,
+    [string]$ComputerName,
+    [pscredential]$Credential,
+    [ValidateSet('Inspect', 'Switch', 'Rollback')][string]$Mode = 'Inspect',
+    [string]$NewUrl,
+    [string]$KeepOldAs,
+    [string]$StateFile,
+    [string]$StagingRoot,
+    [string]$ConfigPath,
+    [switch]$VerifyWithGhToken
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'PortCommon.ps1')
+$config = Get-PortConfig $ConfigPath
+if (-not $KeepOldAs) { $KeepOldAs = Get-PortConfigValue $config 'oldRemoteName' 'old-origin' }
+
+$where = if ($ComputerName) { $ComputerName } else { $env:COMPUTERNAME }
+if (-not $StateFile) {
+    $dir = Join-Path (Get-PortStagingRoot $config $StagingRoot) 'cutover'
+    New-Item -ItemType Directory -Force -Path $dir | Out-Null
+    $safe = ($Path -replace '[:\\/ ]+', '_').Trim('_')
+    $StateFile = Join-Path $dir "$where-$safe.json"
+}
+
+# One script block, run locally or remotely. Windows PowerShell 5.1 compatible. Native stderr
+# must not become a terminating error, so git runs under 'Continue' and is judged by exit code.
+$block = {
+    param($P, $M, $New, $KeepAs, $OldUrl, $RestoreUrl, $AddedRemote, $Token)
+    $ErrorActionPreference = 'Continue'
+    function G { $o = & git -c safe.directory=* -C $P @args 2>&1; $c = $LASTEXITCODE; return @{ code = $c; out = @($o | ForEach-Object { "$_" }) } }
+    $r = @{ ok = $false; origin = $null; branch = $null; head = $null; dirty = 0; remotes = @(); message = $null; addedRemote = $false; rolledBack = $false }
+    if (-not (Test-Path -LiteralPath $P)) { $r.message = "Path not found: $P"; return $r }
+    $o = G remote get-url origin
+    if ($o.code -ne 0) { $r.message = "No origin remote in $P"; return $r }
+    $r.origin = ($o.out -join '')
+    $b = G symbolic-ref --short HEAD; if ($b.code -eq 0) { $r.branch = ($b.out -join '') }
+    $hd = G rev-parse --verify -q HEAD
+    if ($hd.code -ne 0 -or -not ($hd.out -join '')) { $r.message = "$P has no commit at HEAD (empty or unborn repository)"; return $r }
+    $r.head = ($hd.out -join '')
+    $r.dirty = @((G status --porcelain).out | Where-Object { $_ }).Count
+    $r.remotes = @((G remote).out)
+
+    if ($M -eq 'Inspect') { $r.ok = $true; return $r }
+
+    if ($M -eq 'Rollback') {
+        $s = G remote set-url origin $OldUrl
+        if ($s.code -ne 0) { $r.message = "set-url failed: $($s.out -join ' ')"; return $r }
+        if ($AddedRemote -and ($r.remotes -contains $KeepAs)) { G remote remove $KeepAs | Out-Null }
+        $r.origin = $OldUrl; $r.ok = $true; $r.message = 'rolled back'; return $r
+    }
+
+    # Switch
+    if ($r.origin -eq $New) { $r.ok = $true; $r.message = 'origin already points at the new URL'; return $r }
+    if (-not ($r.remotes -contains $KeepAs)) {
+        $a = G remote add $KeepAs $OldUrl
+        if ($a.code -ne 0) { $r.message = "could not add remote ${KeepAs}: $($a.out -join ' ')"; return $r }
+        $r.addedRemote = $true
+    }
+    $s = G remote set-url origin $New
+    if ($s.code -ne 0) { $r.message = "set-url failed: $($s.out -join ' ')"; return $r }
+
+    # From here origin points at the new URL. ANY failure, including an exception, must restore it.
+    $fail = $null
+    $env:GIT_TERMINAL_PROMPT = '0'
+    try {
+        if ($Token) {
+            $env:GIT_CONFIG_COUNT = '1'
+            $env:GIT_CONFIG_KEY_0 = 'http.https://github.com/.extraheader'
+            $env:GIT_CONFIG_VALUE_0 = 'AUTHORIZATION: basic ' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("x-access-token:$Token"))
+        }
+        $f = G fetch -q origin
+        $contained = @()
+        if ($f.code -eq 0) { $contained = @((G for-each-ref --contains HEAD --format='%(refname)' refs/remotes/origin).out | Where-Object { $_ }) }
+        if ($f.code -ne 0) { $fail = "fetch from the new origin failed (exit $($f.code)): $(($f.out | Select-Object -First 3) -join ' ')" }
+        elseif ($contained.Count -eq 0) { $fail = "HEAD $($r.head.Substring(0,12)) is not contained in any origin/* branch: this checkout has commits GitHub does not" }
+    }
+    catch { $fail = "verification threw: $($_.Exception.Message)" }
+    finally {
+        Remove-Item Env:GIT_CONFIG_COUNT, Env:GIT_CONFIG_KEY_0, Env:GIT_CONFIG_VALUE_0 -ErrorAction SilentlyContinue
+    }
+    if ($fail) {
+        G remote set-url origin $RestoreUrl | Out-Null
+        if ($r.addedRemote) { G remote remove $KeepAs | Out-Null; $r.addedRemote = $false }
+        $r.rolledBack = $true; $r.message = $fail; return $r
+    }
+    $r.origin = $New; $r.ok = $true; $r.message = "HEAD is contained in: $($contained -join ', ')"; return $r
+}
+
+function Invoke-Block($ArgList) {
+    if ($ComputerName) {
+        $sa = @{ ComputerName = $ComputerName; ScriptBlock = $block; ArgumentList = $ArgList }
+        if ($Credential) { $sa.Credential = $Credential }
+        return Invoke-Command @sa
+    }
+    return & $block @ArgList
+}
+
+# Always inspect first.
+$now = Invoke-Block @($Path, 'Inspect', $null, $KeepOldAs, $null, $null, $false, $null)
+if (-not $now.ok) { throw "[$where] $($now.message)" }
+$clean = Remove-UrlCredential $now.origin
+Write-Host ("[{0}] {1}`n    origin : {2}`n    branch : {3}   HEAD {4}   uncommitted: {5}   remotes: {6}" -f $where, $Path, $clean.Url, $now.branch, $now.head.Substring(0, 12), $now.dirty, ($now.remotes -join ', '))
+if ($clean.HadCredential) { Write-PortWarn 'The current origin URL EMBEDS A CREDENTIAL. It is shown without it. Rotate that credential after the cutover.' }
+if ($Mode -eq 'Inspect') { exit 0 }
+
+if ($Mode -eq 'Switch') {
+    if (-not $NewUrl) { throw '-NewUrl is required for -Mode Switch.' }
+    if ($now.dirty -gt 0) { Write-PortWarn "The checkout has $($now.dirty) uncommitted change(s). A deploy that resets the tree will discard them. Look before you continue." }
+    if (-not $PSCmdlet.ShouldProcess("$where $Path", "Set origin to $NewUrl")) { exit 0 }
+    $token = $null
+    if ($VerifyWithGhToken) {
+        $token = (& gh auth token 2>$null)
+        if ($LASTEXITCODE -ne 0 -or -not $token) { throw 'gh auth token returned nothing. Sign in with gh auth login, or drop -VerifyWithGhToken.' }
+    }
+    # Record the rollback BEFORE changing anything.
+    $state = [ordered]@{
+        computer = $where; path = $Path; oldUrl = $clean.Url; oldUrlHadCredential = $clean.HadCredential
+        newUrl = $NewUrl; keepOldAs = $KeepOldAs; addedRemote = $false; switchedAt = (Get-Date).ToString('o'); headAtSwitch = $now.head
+    }
+    ConvertTo-PortJsonFile $state $StateFile
+    # The second remote gets the credential-free URL. On failure the ORIGINAL value is restored.
+    try {
+        $res = Invoke-Block @($Path, 'Switch', $NewUrl, $KeepOldAs, $clean.Url, $now.origin, $false, $token)
+    }
+    catch {
+        # The call itself failed (e.g. the WinRM transport dropped). The remote side may or may
+        # not have changed origin. Put the ORIGINAL value back; leave the kept remote for a human.
+        $token = $null
+        Write-PortFail "[$where] Switch call failed: $($_.Exception.Message). Restoring the original origin."
+        try { $null = Invoke-Block @($Path, 'Rollback', $null, $KeepOldAs, $now.origin, $null, $false, $null) } catch { Write-PortFail "[$where] Restore ALSO failed. Set origin back by hand to the URL in $StateFile." }
+        exit 1
+    }
+    $token = $null
+    if (-not $res.ok) {
+        if ($res.rolledBack) { Write-PortFail "[$where] Switch failed and was ROLLED BACK: $($res.message)" }
+        else { Write-PortFail "[$where] Switch failed: $($res.message)" }
+        Remove-Item -LiteralPath $StateFile -ErrorAction SilentlyContinue
+        exit 1
+    }
+    $state.addedRemote = [bool]$res.addedRemote
+    ConvertTo-PortJsonFile $state $StateFile
+    Write-PortOk "[$where] origin -> $NewUrl. $($res.message)"
+    Write-Host "    old origin kept as remote '$KeepOldAs'. Rollback: $($MyInvocation.MyCommand.Name) -Path '$Path'$(if ($ComputerName) { " -ComputerName $ComputerName" }) -Mode Rollback"
+    Write-Host "    state: $StateFile"
+    exit 0
+}
+
+if ($Mode -eq 'Rollback') {
+    if (-not (Test-Path -LiteralPath $StateFile)) { throw "No state file at $StateFile. Pass -StateFile." }
+    $state = Get-Content -LiteralPath $StateFile -Raw | ConvertFrom-Json
+    if (-not $PSCmdlet.ShouldProcess("$where $Path", "Set origin back to $($state.oldUrl)")) { exit 0 }
+    $res = Invoke-Block @($Path, 'Rollback', $null, $state.keepOldAs, $state.oldUrl, $null, [bool]$state.addedRemote, $null)
+    if (-not $res.ok) { Write-PortFail "[$where] Rollback failed: $($res.message)"; exit 1 }
+    if ($state.oldUrlHadCredential) { Write-PortWarn 'The old URL had an embedded credential. It was restored WITHOUT it; the credential helper must supply one.' }
+    Write-PortOk "[$where] origin restored to $($state.oldUrl)"
+    exit 0
+}