@caddis/cli 0.4.22 → 0.4.24

package/bundles/codex/.codex/skills/devops/port-to-github/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: port-to-github
-description: Move (port) an app or repository to GitHub from ANY source - a Gitea/GitLab/any git server URL, a local folder, a network (UNC) share, or a folder on a remote Windows box reached over WinRM - with or without existing git history. Keeps every branch and tag, verifies by SHA, translates Gitea/Forgejo Actions CI, switches deploy checkouts to GitHub with automatic rollback, and retires the old host safely. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", or "cut the deploy over to GitHub".
+description: Move (port) an app or repository to GitHub from ANY source - a Gitea/GitLab/any git server URL, a local folder, a network (UNC) share, or a folder on a remote Windows box reached over WinRM - with or without existing git history. Keeps every branch and tag, verifies by SHA, translates Gitea/Forgejo Actions CI, enforces a source-only content policy (runtimes, binaries, data exports and dependencies stay out of the repo, over ALL history, with a runtime manifest and provisioning script so the environment is still reproducible), switches deploy checkouts to GitHub with automatic rollback, and retires the old host safely. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", "keep binaries / MariaDB / PHP out of the repo", "check the repo only holds source", or "cut the deploy over to GitHub".
 ---
 
 # port-to-github
 
 Move one app to GitHub without losing history, leaking a secret, or breaking its deploy.
 
-The work is in **six phases**. Each ends in a check that can FAIL. Do not start a phase until
+The work is in **six phases**, plus the content policy (2b). Each ends in a check that can FAIL. Do not start a phase until
 the one before it passed. Scripts are in `scripts/` next to this file. They are PowerShell 7
 (`pwsh`); the parts that run on a remote box are Windows PowerShell 5.1 compatible.
 
@@ -15,6 +15,7 @@ the one before it passed. Scripts are in `scripts/` next to this file. They are
 |---|---|---|
 | 1. Stage the source | `Get-PortSource.ps1` | No. The source is only read. |
 | 2. Readiness | `Test-PortReadiness.ps1` | No. |
+| 2b. Content policy | `Test-PortContentPolicy.ps1`, `New-PortRuntimeManifest.ps1`, `Invoke-PortHistoryClean.ps1` | No. Rewrites only the local stage. |
 | 3. Publish | `Publish-PortToGitHub.ps1` | **Yes: creates a GitHub repo and pushes.** |
 | 4. CI | `Convert-PortWorkflow.ps1`, `Test-PortWorkflowParses.ps1` | Yes: a feature branch and a PR. |
 | 5. Cutover | `Switch-CheckoutOrigin.ps1` | **Yes: changes where a deploy host pulls from.** |
@@ -64,6 +65,9 @@ Read the output. These need a decision, not a shrug:
 - **Uncommitted changes** in a source checkout are left out unless you pass
   `-IncludeUncommitted`, which puts them on a separate branch `port/uncommitted-snapshot-*`.
   The real branches stay exactly as committed. Ask the user which they want.
+- **Default branch.** From a server or a bare repository, its HEAD. From a WORKING checkout,
+  `main` (or `master`) when it exists, because the checked-out branch is only what someone had
+  open; the script says when it made that choice. Override with `-DefaultBranch <name>`.
 - **Remote-only branches**: branches the checkout only knows as `origin/x`. If the checkout is
   the only copy, re-run with `-PromoteRemoteBranches origin`. If a server has them, port from it.
 - **Likely secrets** in a plain folder or a snapshot stop the script (exit 2). Nothing has left
@@ -93,6 +97,63 @@ deploy jobs included. Readiness lists those branches; publish refuses them unles
 (the new repo will expose them), CI credentials, dependency hosts, runner labels, files that
 still name the old host. The report is in `readiness.json`.
 
+## Phase 2b - content policy: source only
+
+**The rule.** The repository holds application code, configuration and templates, migration
+SCRIPTS, tests, and the scripts and manifests that rebuild the environment. Runtime and server
+distributions (MariaDB, PHP, JDK, Node, Python, Apache...), binaries and archives, database data
+files, data exports and installed dependencies stay OUT, and are installed or provisioned
+separately. This is the default for every port; a project narrows or widens it with a
+`contentPolicy` block in its config (`keep` / `exclude` regexes, `dataThresholdMB`, `largeMB`).
+
+```powershell
+& $s/Test-PortContentPolicy.ps1 -Name <repo-name>
+```
+
+It checks the default branch AND every blob in history, because **`.gitignore` does not remove a
+file that was committed before it**. Exit 1 means excluded content exists somewhere in history.
+The output groups findings by folder; `content-policy.json` has every path.
+
+For each group, decide with the user:
+
+1. **It belongs** (a small fixture, a vendored library the team maintains) -> add a `keep` regex
+   to the project config and re-run.
+2. **It does not** -> remove it from the STAGE's history. Two ways, and it is the owner's call:
+   ```powershell
+   & $s/Invoke-PortHistoryClean.ps1 -Name <repo-name> -Mode Rewrite      # keep history, drop the paths
+   & $s/Invoke-PortHistoryClean.ps1 -Name <repo-name> -Mode FreshStart   # one commit of today's files
+   ```
+   `Rewrite` keeps every branch, tag and commit but CHANGES commit SHAs from the first affected
+   commit on; anything quoting an old SHA stops matching. `FreshStart` is smallest and drops all
+   history, other branches and tags. Both re-run the policy check and exit 1 if anything
+   excluded survived. The source keeps its original history either way.
+
+**Keep the environment reproducible.** Excluding a runtime is only safe if the repo says how to
+get it back. Scan the SOURCE FOLDER (runtimes usually live in an ignored `tools/`):
+
+```powershell
+& $s/New-PortRuntimeManifest.ps1 -Path <source-folder> [-ComputerName <box>] -OutDir <clone>\environment
+```
+
+It writes `runtimes.json` (kind, exact version, binary SHA-256, data folders), `provision.ps1`
+(downloads and unpacks each runtime with a known public source and FAILS for any it cannot
+provision), `README.md`, and `config-templates/`: configuration found inside runtime folders
+(`my.ini`, `php.ini`, `config/`, `metadata/`). Configuration is app content even when the runtime
+around it is not. Files that look like they hold a credential are withheld and listed; make
+those templates by hand with placeholders. **The credential check is a heuristic: read every
+copied template yourself before committing it.** The dogfood found one it missed (a SAML test
+user written as `'name:password' => array(...)`); the rule now covers that form, but the next
+form may be new. Nothing it finds is executed; versions come from file
+metadata. Commit `environment/` on the phase 4 branch, by file name.
+
+Two things it cannot decide, so you must:
+- **UNCLASSIFIED folders** beside a runtime (a deployed web tree, a library with no binary).
+  Decide each: provision it, rebuild it from repo code, or keep it in the repo.
+- **Data folders** (e.g. a database `data/` directory). This is state, not code. The repo carries
+  the schema and migrations; the data comes from a backup. Say where that backup lives.
+
+Then add every excluded folder to `.gitignore` on the phase 4 branch, so it cannot come back.
+
 ## Phase 3 - publish (ask first)
 
 Tell the user: the repo name, owner, visibility, branch and tag counts. Then:
@@ -101,7 +162,7 @@ Tell the user: the repo name, owner, visibility, branch and tag counts. Then:
 & $s/Publish-PortToGitHub.ps1 -Name <repo-name> [-Owner <org>] [-Visibility private]
 ```
 
-It first checks the stage still holds exactly the refs phase 1 recorded (anything else would be
+It refuses a stage whose content policy is not compliant (run phase 2b; `-AcceptContentPolicy` records an explicit owner exception instead). It then checks the stage still holds exactly the refs phase 1 recorded (anything else would be
 pushed and then "verified" against itself), creates the repo EMPTY, pushes `refs/heads/*` and
 `refs/tags/*` with an explicit refspec, sets the default branch, and compares every ref by SHA
 (exit 1 on any difference). Do not run other git commands inside the stage; if you did,

package/bundles/codex/.codex/skills/devops/port-to-github/scripts/Get-PortSource.ps1

@@ -37,6 +37,9 @@ param(
     # What to do when a plain folder or an uncommitted snapshot contains a likely secret.
     [ValidateSet('Stop', 'Exclude')][string]$OnSecret = 'Stop',
     [string]$InitialBranch = 'main',
+    # The GitHub default branch. Default: the server's HEAD; for a working checkout, main/master
+    # when present (the checked-out branch is only what someone had open).
+    [string]$DefaultBranch,
     # Replace an existing staging folder for this Name.
     [switch]$Force
 )
@@ -315,6 +318,7 @@ switch ($kind) {
                     }
                 }
                 $r.isRepo = $isRepo
+                $r.isBare = $isBare
                 if ($isRepo) {
                     $bundle = Join-Path $tmp 'repo.bundle'
                     & $git -c safe.directory=* -C $Path bundle create $bundle --all 2>&1 | Out-Null
@@ -362,7 +366,13 @@ switch ($kind) {
                 Invoke-PortGit @('bundle', 'verify', $localBundle) | Out-Null
                 Invoke-PortGit @('clone', '-q', '--mirror', $localBundle, $mirror) | Out-Null
                 $manifest.hadGitHistory = $true
-                $manifest.sourceHead = if ($remote.head) { $remote.head } else { $remote.headSha }
+                # A bare repository's HEAD is authoritative, like a server's; only a WORKING checkout's
+                # HEAD is 'whatever was open'. Leaving sourceHead empty keeps the main-line preference off.
+                $manifest.sourceHead = if ($remote.isBare) { $null } elseif ($remote.head) { $remote.head } else { $remote.headSha }
+                # A bundle records HEAD as a commit, not a branch name, so a clone of it GUESSES the
+                # default when two branches share that commit. For a bare repo the name read on the
+                # far side is authoritative; carry it across.
+                if ($remote.isBare -and $remote.head) { $authHead = $remote.head }
                 $manifest.dirtyFiles = @($remote.dirty)
                 if ($manifest.dirtyFiles.Count -gt 0) {
                     if ($IncludeUncommitted -and $remote.dirtyZip) {
@@ -430,11 +440,29 @@ if ($heads.Count -eq 0) { throw "The source produced no branches. Nothing to por
 
 $symHead = Invoke-PortGit -AllowFailure @('-C', $mirror, 'symbolic-ref', '--short', 'HEAD')
 $def = if ($symHead.ExitCode -eq 0) { $symHead.Output -join '' } else { $null }
+$mainLine = @('main', 'master') | Where-Object { $headNames -contains $_ } | Select-Object -First 1
+if (-not (Get-Variable -Name authHead -ErrorAction SilentlyContinue)) { $authHead = $null }
+# The branch the source checkout was really on (a bundle's HEAD is only a guess), so the
+# main-line choice below can say what it replaced.
+if ($manifest.sourceHead -and ($headNames -contains $manifest.sourceHead)) { $def = $manifest.sourceHead }
+if ($DefaultBranch) {
+    if (-not ($headNames -contains $DefaultBranch)) { throw "-DefaultBranch '$DefaultBranch' is not a branch in the source." }
+    $def = $DefaultBranch
+}
+elseif ($authHead -and ($headNames -contains $authHead)) {
+    $def = $authHead
+}
+elseif ($kind -ne 'url' -and $manifest.sourceHead -and $mainLine -and $def -ne $mainLine) {
+    # A server's HEAD IS its default branch. A working checkout's HEAD is only whatever branch
+    # someone had open, so prefer the main line when there is one, and say so.
+    $manifest.warnings += "The checkout was on '$def', but '$mainLine' exists, so '$mainLine' is the default branch on GitHub. Pass -DefaultBranch to choose another."
+    $def = $mainLine
+}
 if (-not $def -or -not ($headNames -contains $def)) {
     $def = @('main', 'master', 'develop') | Where-Object { $headNames -contains $_ } | Select-Object -First 1
     if (-not $def) { $def = $headNames[0] }
-    Invoke-PortGit @('-C', $mirror, 'symbolic-ref', 'HEAD', "refs/heads/$def") | Out-Null
 }
+Invoke-PortGit @('-C', $mirror, 'symbolic-ref', 'HEAD', "refs/heads/$def") | Out-Null
 $manifest.defaultBranch = $def
 
 if ($manifest.remoteOnlyBranches.Count -gt 0) {

package/bundles/codex/.codex/skills/devops/port-to-github/scripts/Invoke-PortHistoryClean.ps1

@@ -0,0 +1,123 @@
+<#
+.SYNOPSIS
+  Remove excluded paths from the STAGED repository's history, then prove they are gone.
+
+.DESCRIPTION
+  Works only on <staging>\<Name>\mirror.git. The source is never touched.
+
+  -Mode Rewrite     keep every branch, tag and commit, minus the excluded paths. Commit SHAs
+                    change from the first commit that touched an excluded path onward, so
+                    anything that quotes an old SHA (a deploy record, a tag note) stops matching.
+                    Uses git filter-repo if installed, otherwise git filter-branch.
+  -Mode FreshStart  one new commit holding the default branch's current files minus the excluded
+                    paths. All other branches, tags and history are dropped. Smallest, simplest,
+                    and loses the history - an owner decision.
+
+  Paths come from content-policy-exclude.txt (written by Test-PortContentPolicy.ps1) unless
+  -PathsFile is given. Afterwards it re-runs Test-PortContentPolicy.ps1, which must exit 0, and
+  rewrites manifest.json's heads and tags so Publish's stage-drift check sees the cleaned refs.
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [Parameter(Mandatory)][string]$Name,
+    [Parameter(Mandatory)][ValidateSet('Rewrite', 'FreshStart')][string]$Mode,
+    [string]$PathsFile,
+    [string]$StagingRoot,
+    [string]$ConfigPath
+)
+
+$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." }
+if (-not $PathsFile) { $PathsFile = Join-Path $stage 'content-policy-exclude.txt' }
+if (-not (Test-Path -LiteralPath $PathsFile)) { throw "No paths file at $PathsFile. Run Test-PortContentPolicy.ps1 first." }
+$paths = @(Get-Content -LiteralPath $PathsFile | Where-Object { $_ -and $_.Trim() })
+if ($paths.Count -eq 0) { Write-PortOk 'Nothing to remove.'; exit 0 }
+$manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json
+$branch = $manifest.defaultBranch
+
+# git reads pathspecs as patterns; ":(literal)" makes every entry an exact path, so a file
+# named with [ ] * ? is never widened into a glob that removes something else.
+$specFile = Join-Path $stage 'history-clean-pathspec.txt'
+[IO.File]::WriteAllLines($specFile, [string[]]@($paths | ForEach-Object { ":(literal)$_" }), (New-Object Text.UTF8Encoding($false)))
+
+$before = @(Invoke-PortGit @('-C', $mirror, 'for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads', 'refs/tags'))
+if (-not $PSCmdlet.ShouldProcess($mirror, "$Mode history, removing $($paths.Count) path(s)")) { exit 0 }
+
+if ($Mode -eq 'Rewrite') {
+    $fr = Invoke-PortGit -AllowFailure @('filter-repo', '--version')
+    if ($fr.ExitCode -eq 0) {
+        Write-PortStep "Rewriting with git filter-repo ($($paths.Count) path(s))"
+        $plain = Join-Path $stage 'history-clean-paths.txt'
+        [IO.File]::WriteAllLines($plain, [string[]]$paths, (New-Object Text.UTF8Encoding($false)))
+        Invoke-PortGit @('-C', $mirror, 'filter-repo', '--force', '--invert-paths', '--paths-from-file', $plain) | Out-Null
+    }
+    else {
+        Write-PortStep "Rewriting with git filter-branch ($($paths.Count) path(s)); git filter-repo is not installed"
+        $env:FILTER_BRANCH_SQUELCH_WARNING = '1'
+        # The index filter is eval'd by a shell. Pass the path through an environment variable, so a
+        # quote in it (C:\Users\O'Brien\...) cannot break the command.
+        $env:PORT_PATHSPEC_FILE = $specFile.Replace('\', '/')
+        try {
+            $idx = 'git rm -r --cached --ignore-unmatch --quiet --pathspec-from-file="$PORT_PATHSPEC_FILE"'
+            Invoke-PortGit @('-C', $mirror, 'filter-branch', '-f', '--index-filter', $idx, '--prune-empty', '--tag-name-filter', 'cat', '--', '--all') | Out-Null
+        }
+        finally { Remove-Item Env:FILTER_BRANCH_SQUELCH_WARNING, Env:PORT_PATHSPEC_FILE -ErrorAction SilentlyContinue }
+        foreach ($r in @(Invoke-PortGit @('-C', $mirror, 'for-each-ref', '--format=%(refname)', 'refs/original'))) {
+            if ($r) { Invoke-PortGit @('-C', $mirror, 'update-ref', '-d', $r) | Out-Null }
+        }
+    }
+}
+else {
+    Write-PortStep "Fresh start: one commit from $branch minus $($paths.Count) path(s)"
+    $tmpIndex = Join-Path $stage 'fresh.index'
+    # git rm needs a work tree even with --cached; a bare mirror has none, so lend it an empty one.
+    $tmpWork = Join-Path $stage 'fresh-worktree'
+    New-Item -ItemType Directory -Force -Path $tmpWork | Out-Null
+    $env:GIT_INDEX_FILE = $tmpIndex
+    $env:GIT_WORK_TREE = $tmpWork
+    try {
+        Invoke-PortGit @('-C', $mirror, 'read-tree', $branch) | Out-Null
+        Invoke-PortGit @('-C', $mirror, 'rm', '-r', '--cached', '--ignore-unmatch', '--quiet', "--pathspec-from-file=$specFile") | Out-Null
+        $tree = (Invoke-PortGit @('-C', $mirror, 'write-tree')) -join ''
+    }
+    finally {
+        Remove-Item Env:GIT_INDEX_FILE, Env:GIT_WORK_TREE -ErrorAction SilentlyContinue
+        Remove-Item -LiteralPath $tmpIndex -ErrorAction SilentlyContinue
+        Remove-Item -LiteralPath $tmpWork -Recurse -Force -ErrorAction SilentlyContinue
+    }
+    $msg = "Initial import of $Name (fresh start: history not carried over)"
+    $body = "Source: $($manifest.source), branch $branch at $((Invoke-PortGit @('-C', $mirror, 'rev-parse', $branch)) -join ''). $($paths.Count) path(s) excluded by the content policy."
+    $commit = (Invoke-PortGit @('-C', $mirror, 'commit-tree', $tree, '-m', $msg, '-m', $body)) -join ''
+    foreach ($r in @(Invoke-PortGit @('-C', $mirror, 'for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/tags'))) {
+        if ($r) { Invoke-PortGit @('-C', $mirror, 'update-ref', '-d', $r) | Out-Null }
+    }
+    Invoke-PortGit @('-C', $mirror, 'update-ref', "refs/heads/$branch", $commit) | Out-Null
+    Invoke-PortGit @('-C', $mirror, 'symbolic-ref', 'HEAD', "refs/heads/$branch") | Out-Null
+}
+
+# Drop the unreachable objects, so a later readiness scan measures what will actually be pushed.
+Invoke-PortGit @('-C', $mirror, 'reflog', 'expire', '--expire=now', '--all') | Out-Null
+Invoke-PortGit @('-C', $mirror, 'gc', '--prune=now', '--quiet') | Out-Null
+
+$after = @(Invoke-PortGit @('-C', $mirror, 'for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads', 'refs/tags'))
+$manifest.heads = @(Invoke-PortGit @('-C', $mirror, 'for-each-ref', '--format=%(refname:short) %(objectname)', 'refs/heads'))
+$manifest.tags = @(Invoke-PortGit @('-C', $mirror, 'for-each-ref', '--format=%(refname:short) %(objectname)', 'refs/tags'))
+$manifest | Add-Member -NotePropertyName historyClean -NotePropertyValue ([pscustomobject]@{
+        mode = $Mode; at = (Get-Date).ToString('o'); pathsRemoved = $paths.Count
+        refsBefore = $before.Count; refsAfter = $after.Count
+        note = 'Commit SHAs changed. The source still holds the original history.'
+    }) -Force
+ConvertTo-PortJsonFile $manifest $manifestPath
+
+# The proof: the policy must now pass. A clean that cannot fail is not a clean.
+Write-PortStep 'Re-checking the content policy on the cleaned history'
+& (Join-Path $PSScriptRoot 'Test-PortContentPolicy.ps1') -Name $Name -StagingRoot $StagingRoot -ConfigPath $ConfigPath
+if ($LASTEXITCODE -ne 0) { Write-PortFail 'Excluded content is STILL in history after the clean. Do not publish.'; exit 1 }
+Write-PortOk ("History cleaned ({0}): refs {1} -> {2}. Re-run Test-PortReadiness.ps1 before publishing." -f $Mode, $before.Count, $after.Count)
+exit 0

package/bundles/codex/.codex/skills/devops/port-to-github/scripts/New-PortRuntimeManifest.ps1

@@ -0,0 +1,258 @@
+<#
+.SYNOPSIS
+  Record the runtimes an app needs but the repository must not carry, so the environment can
+  be rebuilt from the repository alone.
+
+.DESCRIPTION
+  Scans the app's SOURCE FOLDER (not the git history), including ignored folders such as tools/,
+  for runtime distributions: MariaDB/MySQL, PHP, Node, Python, Java, Apache, nginx, Redis,
+  PostgreSQL. Versions come from file metadata. NOTHING it finds is executed.
+
+  Writes to -OutDir (put it in the repository, e.g. environment/):
+    runtimes.json      name, version, where it lived, binary SHA-256, data folders, config files
+    README.md          the same for people, plus every decision still open
+    provision.ps1      downloads and unpacks each runtime with a known public source; fails
+                       loudly for any runtime it cannot provision, so a gap is never silent
+    config-templates/  configuration found INSIDE runtime folders (my.ini, php.ini, config/,
+                       metadata/). The teammate rule keeps configuration in the repo even when
+                       the runtime around it is excluded. A file that looks like it holds a
+                       credential is NOT copied; it is listed for a hand-made template.
+
+  Folders beside a runtime that match nothing (a deployed web tree, a vendored library) are
+  listed as UNCLASSIFIED: each needs a human decision.
+
+  Works on a local or UNC path, or on a remote box with -ComputerName (Windows PowerShell 5.1
+  on the far side is fine).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$Path,
+    [string]$ComputerName,
+    [pscredential]$Credential,
+    [Parameter(Mandatory)][string]$OutDir,
+    [int]$MaxDepth = 5,
+    [int]$ConfigMaxKB = 256
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'PortCommon.ps1')
+
+# Runs locally or remotely. 5.1-compatible, read-only, never executes a found binary.
+$scan = {
+    param($Root, $Depth, $CfgMaxKB)
+    $ErrorActionPreference = 'Continue'
+    $res = @{ ok = $false; error = $null; runtimes = @(); unclassified = @() }
+    if (-not (Test-Path -LiteralPath $Root -PathType Container)) { $res.error = "Folder not found: $Root"; return $res }
+    $Root = (Resolve-Path -LiteralPath $Root).ProviderPath.TrimEnd('\')
+    function Rel($p) { $p.Substring($Root.Length).TrimStart('\').Replace('\', '/') }
+    # A plain loop: Measure-Object over an EMPTY folder has no .Sum under strict mode, and an
+    # empty data/ folder (a runtime never started) is normal here.
+    function DirMB($p) { $t = [int64]0; foreach ($f in @(Get-ChildItem -LiteralPath $p -Recurse -File -Force -ErrorAction SilentlyContinue)) { $t += $f.Length }; [math]::Round($t / 1MB, 1) }
+
+    $binRx = '(?i)^(mariadbd|mysqld|php|node|python|java|httpd|nginx|redis-server|postgres)\.exe$'
+    $skipRx = '(?i)\\(node_modules|\.venv|venv|\.git|site-packages|vendor)\\'
+    $bins = @(Get-ChildItem -LiteralPath $Root -Recurse -Depth $Depth -File -Force -ErrorAction SilentlyContinue |
+        Where-Object { $_.Name -match $binRx -and $_.FullName -notmatch $skipRx })
+    $roots = @{}
+    $priority = @('mariadbd', 'mysqld', 'php', 'node', 'python', 'java', 'httpd', 'nginx', 'redis-server', 'postgres')
+    foreach ($b in $bins) {
+        $dir = $b.Directory
+        $rootDir = if ($dir.Name -ieq 'bin' -and $dir.Parent) { $dir.Parent.FullName } else { $dir.FullName }
+        if ($rootDir -ieq $Root) { continue }
+        $base = [IO.Path]::GetFileNameWithoutExtension($b.Name).ToLower()
+        if (-not $roots.ContainsKey($rootDir) -or ($priority.IndexOf($base) -lt $priority.IndexOf($roots[$rootDir].base))) {
+            $roots[$rootDir] = @{ file = $b; base = $base }
+        }
+    }
+    # A runtime nested inside another runtime (php inside apache/) belongs to the outer one.
+    $rootList = @($roots.Keys | Sort-Object Length)
+    $kept = @()
+    foreach ($r in $rootList) { if (-not ($kept | Where-Object { $r.StartsWith($_ + '\', [StringComparison]::OrdinalIgnoreCase) })) { $kept += $r } }
+
+    $cfgExt = '(?i)\.(ini|cnf|conf|php|ya?ml|json|xml|properties|toml)$'
+    function Get-Configs($dir, $dataDirs) {
+        $out = @()
+        $cands = @(Get-ChildItem -LiteralPath $dir -File -Force -ErrorAction SilentlyContinue | Where-Object { $_.Name -match '(?i)\.(ini|cnf|conf)$' })
+        foreach ($sub in @(Get-ChildItem -LiteralPath $dir -Directory -Force -ErrorAction SilentlyContinue | Where-Object { $_.Name -match '(?i)^(conf|config|etc|metadata|cert)$' })) {
+            $cands += @(Get-ChildItem -LiteralPath $sub.FullName -Recurse -Depth 2 -File -Force -ErrorAction SilentlyContinue | Where-Object { $_.Name -match $cfgExt -or $sub.Name -ieq 'cert' })
+        }
+        foreach ($f in $cands) {
+            if ($dataDirs | Where-Object { $f.FullName.StartsWith($_ + '\', [StringComparison]::OrdinalIgnoreCase) }) { continue }
+            if ($f.Name -match '(?i)\.(dist|example|sample|template)$') { continue }
+            $o = @{ rel = (Rel $f.FullName); bytes = $f.Length; b64 = $null; tooBig = $false }
+            if ($f.Length -le ($CfgMaxKB * 1KB)) { $o.b64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes($f.FullName)) } else { $o.tooBig = $true }
+            $out += $o
+        }
+        return , $out
+    }
+
+    foreach ($rd in $kept) {
+        $e = $roots[$rd]; $vi = $e.file.VersionInfo
+        $ver = "$($vi.ProductVersion)".Trim(); if (-not $ver) { $ver = "$($vi.FileVersion)".Trim() }
+        $kind = switch -Regex ($e.base) { '^(mariadbd|mysqld)$' { if ("$($vi.ProductName)$($vi.FileDescription)" -match '(?i)mariadb' -or (Test-Path (Join-Path $rd 'bin\mariadbd.exe'))) { 'mariadb' } else { 'mysql' } } '^php$' { 'php' } '^node$' { 'node' } '^python$' { 'python' } '^java$' { 'java' } '^httpd$' { 'apache' } '^nginx$' { 'nginx' } '^redis-server$' { 'redis' } '^postgres$' { 'postgresql' } default { $e.base } }
+        $sha = (Get-FileHash -LiteralPath $e.file.FullName -Algorithm SHA256).Hash.ToLower()
+        $dataDirs = @(Get-ChildItem -LiteralPath $rd -Directory -Force -ErrorAction SilentlyContinue | Where-Object { $_.Name -match '(?i)^(data|db|pgdata|var)$' } | ForEach-Object { $_.FullName })
+        $ts = $null
+        if ($kind -eq 'php') { $ts = [bool](Get-ChildItem -LiteralPath $rd -Filter 'php*ts.dll' -File -ErrorAction SilentlyContinue) }
+        $res.runtimes += @{
+            kind = $kind; root = (Rel $rd); binary = (Rel $e.file.FullName); version = $ver
+            product = "$($vi.ProductName)"; binarySha256 = $sha; sizeMB = (DirMB $rd); threadSafe = $ts
+            dataDirs = @($dataDirs | ForEach-Object { @{ rel = (Rel $_); sizeMB = (DirMB $_) } })
+            configs = (Get-Configs $rd $dataDirs)
+        }
+    }
+
+    # Siblings of runtime roots that match nothing: a human must decide what they are.
+    $containers = @($kept | ForEach-Object { Split-Path $_ -Parent } | Sort-Object -Unique | Where-Object { $_ -and ($_ -ine $Root) })
+    foreach ($c in $containers) {
+        foreach ($d in @(Get-ChildItem -LiteralPath $c -Directory -Force -ErrorAction SilentlyContinue)) {
+            if ($kept -contains $d.FullName) { continue }
+            $hints = @()
+            $cj = Join-Path $d.FullName 'composer.json'
+            if (Test-Path $cj) { try { $j = Get-Content $cj -Raw | ConvertFrom-Json; $hints += "composer package $($j.name)$(if ($j.version) { ' ' + $j.version })" } catch { $hints += 'composer.json' } }
+            if (Test-Path (Join-Path $d.FullName 'package.json')) { $hints += 'package.json' }
+            foreach ($s in 'conf', 'config', 'cert', 'data', 'log') { if (Test-Path (Join-Path $d.FullName $s)) { $hints += "$s/" } }
+            $res.unclassified += @{ rel = (Rel $d.FullName); sizeMB = (DirMB $d.FullName); hints = $hints; configs = (Get-Configs $d.FullName @()) }
+        }
+    }
+    $res.ok = $true
+    return $res
+}
+
+if ($ComputerName) {
+    $ia = @{ ComputerName = $ComputerName; ScriptBlock = $scan; ArgumentList = @($Path, $MaxDepth, $ConfigMaxKB) }
+    if ($Credential) { $ia.Credential = $Credential }
+    Write-PortStep "Scanning $Path on $ComputerName for runtimes (read-only)"
+    $res = Invoke-Command @ia
+}
+else {
+    Write-PortStep "Scanning $Path for runtimes (read-only)"
+    $res = & $scan $Path $MaxDepth $ConfigMaxKB
+}
+if (-not $res.ok) { throw $res.error }
+
+New-Item -ItemType Directory -Force -Path $OutDir | Out-Null
+$tplRoot = Join-Path $OutDir 'config-templates'
+$withheld = @(); $copied = @(); $tooBig = @()
+function Save-Configs($list) {
+    foreach ($c in @($list)) {
+        if ($c.tooBig) { $script:tooBig += $c.rel; continue }
+        $bytes = [Convert]::FromBase64String($c.b64)
+        $text = [Text.Encoding]::UTF8.GetString($bytes)
+        $leaf = Split-Path $c.rel -Leaf
+        # Heuristics, so they err toward WITHHOLDING. Found by the dogfood: SimpleSAMLphp's
+        # exampleauth writes a user as 'name:password' => array(...), which no key=value rule sees.
+        $secret = (Test-PortSecretName $leaf) -or ($c.rel -match '(?i)(^|/)cert/') -or (Test-PortSecretContent $text) -or
+            ($text -match '(?i)(password|passwd|pass|pwd|secret|salt|token|api_?key|private_?key|auth\.adminpassword|credentials?)\s*[''"]?\s*(=>|=|:)\s*[''"][^''"\s]{4,}[''"]') -or
+            ($text -match '[''"][^''"\s:/]{2,}:[^''"\s]{4,}[''"]\s*=>') -or
+            ($text -match '(?i)[a-z][a-z0-9+.-]*://[^/\s:@''"]+:[^/\s@''"]+@') -or
+            # Unquoted INI/properties form, the one my.ini and php.ini actually use: password=Secret123
+            ($text -match '(?im)^\s*[\w.-]*(password|passwd|pwd|pass|_pw|secret|api[_-]?key|token|credential)s?\s*=\s*[^\s;#]+')
+        if ($secret) { $script:withheld += $c.rel; continue }
+        $dst = Join-Path $tplRoot ($c.rel -replace '/', '\')
+        New-Item -ItemType Directory -Force -Path (Split-Path $dst -Parent) | Out-Null
+        [IO.File]::WriteAllBytes($dst, $bytes)
+        $script:copied += $c.rel
+    }
+}
+foreach ($r in $res.runtimes) { Save-Configs $r.configs }
+foreach ($u in $res.unclassified) { Save-Configs $u.configs }
+
+function Get-Source($r) {
+    $v = ($r.version -split '\.')
+    $v3 = ($v | Select-Object -First 3) -join '.'
+    switch ($r.kind) {
+        'mariadb' { return @("https://archive.mariadb.org/mariadb-$v3/winx64-packages/mariadb-$v3-winx64.zip") }
+        'php' {
+            $mm = [version](($v | Select-Object -First 2) -join '.')
+            $vs = if ($mm -ge [version]'8.4') { 'vs17' } elseif ($mm -ge [version]'8.0') { 'vs16' } else { 'vc15' }
+            $ts = if ($r.threadSafe) { 'Win32' } else { 'nts-Win32' }
+            $f = "php-$v3-$ts-$vs-x64.zip"
+            return @("https://windows.php.net/downloads/releases/$f", "https://windows.php.net/downloads/releases/archives/$f")
+        }
+        'node' { return @("https://nodejs.org/dist/v$v3/node-v$v3-win-x64.zip") }
+        'python' { return @("https://www.python.org/ftp/python/$v3/python-$v3-embed-amd64.zip") }
+        default { return @() }
+    }
+}
+
+$runtimes = @(foreach ($r in $res.runtimes) {
+        [ordered]@{
+            kind = $r.kind; version = $r.version; product = $r.product; wasAt = $r.root; binary = $r.binary
+            binarySha256 = $r.binarySha256; installedSizeMB = $r.sizeMB; threadSafe = $r.threadSafe
+            sources = @(Get-Source $r); archiveSha256 = $null
+            dataDirs = @($r.dataDirs | ForEach-Object { [ordered]@{ path = $_.rel; sizeMB = $_.sizeMB } })
+        }
+    })
+$uncl = @(foreach ($u in $res.unclassified) { [ordered]@{ path = $u.rel; sizeMB = $u.sizeMB; hints = @($u.hints); decision = 'OPEN' } })
+$doc = [ordered]@{
+    generatedAt = (Get-Date).ToString('o'); scannedPath = $Path; computerName = $ComputerName
+    runtimes = $runtimes; unclassified = $uncl
+    configTemplates = @($copied); configWithheld = @($withheld); configTooBig = @($tooBig)
+}
+ConvertTo-PortJsonFile $doc (Join-Path $OutDir 'runtimes.json')
+
+# ---- provision.ps1: downloads what has a known source, and FAILS for the rest ----------------
+$prov = New-Object System.Collections.Generic.List[string]
+$prov.Add('# Generated by port-to-github New-PortRuntimeManifest.ps1. Rebuilds the local runtimes that the')
+$prov.Add('# repository deliberately does not carry. Review the URLs once, then record each archive''s')
+$prov.Add('# SHA-256 in runtimes.json (archiveSha256) so later runs verify the download.')
+$prov.Add('[CmdletBinding()] param([string]$ToolsRoot = (Join-Path $PSScriptRoot ''..\tools''), [switch]$Force)')
+$prov.Add('$ErrorActionPreference = ''Stop''')
+$prov.Add('$spec = Get-Content -LiteralPath (Join-Path $PSScriptRoot ''runtimes.json'') -Raw | ConvertFrom-Json')
+$prov.Add('$missing = @()')
+$prov.Add('New-Item -ItemType Directory -Force -Path $ToolsRoot | Out-Null')
+$prov.Add('foreach ($r in $spec.runtimes) {')
+$prov.Add('    $dest = Join-Path $ToolsRoot (Split-Path $r.wasAt -Leaf)')
+$prov.Add('    if ((Test-Path $dest) -and -not $Force) { Write-Host "[skip] $($r.kind) $($r.version): $dest exists"; continue }')
+$prov.Add('    $replace = Test-Path $dest')
+$prov.Add('    if (@($r.sources).Count -eq 0) { $missing += "$($r.kind) $($r.version) (no known public source)"; continue }')
+$prov.Add('    $zip = Join-Path ([IO.Path]::GetTempPath()) "$($r.kind)-$($r.version).zip"; $got = $false')
+$prov.Add('    foreach ($u in $r.sources) { try { Invoke-WebRequest -Uri $u -OutFile $zip -UseBasicParsing; $got = $true; break } catch { Write-Host "[miss] $u" } }')
+$prov.Add('    if (-not $got) { $missing += "$($r.kind) $($r.version) (download failed)"; continue }')
+$prov.Add('    $h = (Get-FileHash $zip -Algorithm SHA256).Hash.ToLower()')
+$prov.Add('    if ($r.archiveSha256 -and $h -ne $r.archiveSha256) { throw "$($r.kind): archive SHA-256 $h does not match runtimes.json $($r.archiveSha256)" }')
+$prov.Add('    if (-not $r.archiveSha256) { Write-Warning "$($r.kind): unverified download, SHA-256 $h - record it in runtimes.json" }')
+$prov.Add('    $tmp = Join-Path ([IO.Path]::GetTempPath()) "$($r.kind)-$($r.version)-x"; Expand-Archive -LiteralPath $zip -DestinationPath $tmp -Force')
+$prov.Add('    $inner = @(Get-ChildItem $tmp); $src = if ($inner.Count -eq 1 -and $inner[0].PSIsContainer) { $inner[0].FullName } else { $tmp }')
+$prov.Add('    if ($replace) { Remove-Item -LiteralPath $dest -Recurse -Force }   # Move-Item -Force onto a folder NESTS; replace it instead')
+$prov.Add('    Move-Item -LiteralPath $src -Destination $dest; Write-Host "[ok] $($r.kind) $($r.version) -> $dest"')
+$prov.Add('    $bin = Join-Path $ToolsRoot ((Split-Path $r.wasAt -Leaf) + ''/'' + ($r.binary.Substring($r.wasAt.Length).TrimStart(''/'')))')
+$prov.Add('    if (-not (Test-Path $bin)) { $missing += "$($r.kind): expected binary $bin not found after unpack" }')
+$prov.Add('    elseif ((Get-FileHash $bin -Algorithm SHA256).Hash.ToLower() -ne $r.binarySha256) { Write-Warning "$($r.kind): binary differs from the recorded build (different package variant?)" }')
+$prov.Add('}')
+$prov.Add('Write-Host ''Copy config-templates\ into place, fill in every withheld secret, and restore data from its backup - see README.md.''')
+$prov.Add('if ($missing.Count) { $missing | ForEach-Object { Write-Host "[FAIL] $_" }; exit 1 }')
+$prov.Add('exit 0')
+[IO.File]::WriteAllLines((Join-Path $OutDir 'provision.ps1'), [string[]]$prov, (New-Object Text.UTF8Encoding($false)))
+
+# ---- README.md ------------------------------------------------------------------------------------
+$md = New-Object System.Collections.Generic.List[string]
+$md.Add('# Local runtime environment')
+$md.Add('')
+$md.Add('The runtimes below are needed to run this app locally or in UAT. They are NOT in the repository:')
+$md.Add('they are third-party distributions, not application source. `provision.ps1` rebuilds them.')
+$md.Add('Generated by the port-to-github skill; edit freely, but keep `runtimes.json` the source of truth.')
+$md.Add('')
+$md.Add('| Runtime | Version | Was at | Installed MB | Source |')
+$md.Add('|---|---|---|---|---|')
+foreach ($r in $runtimes) { $md.Add(('| {0} | {1} | `{2}` | {3} | {4} |' -f $r.kind, $r.version, $r.wasAt, $r.installedSizeMB, $(if (@($r.sources).Count) { $r.sources[0] } else { '**none known - install by hand**' }))) }
+$data = @($runtimes | ForEach-Object { $k = $_.kind; $_.dataDirs | ForEach-Object { "- ``$($_.path)`` ($k, $($_.sizeMB) MB): runtime STATE, not code. Rebuild from the schema and migrations in this repository, or restore from backup. Never commit it." } })
+if ($data.Count) { $md.Add(''); $md.Add('## Data folders (never committed)'); $data | ForEach-Object { $md.Add($_) } }
+if ($uncl.Count) {
+    $md.Add(''); $md.Add('## OPEN: folders beside the runtimes that nothing identified')
+    $md.Add('Decide each: provision it (add it here), rebuild it from repository code, or keep it in the repository.')
+    foreach ($u in $uncl) { $md.Add(('- `{0}` ({1} MB){2}' -f $u.path, $u.sizeMB, $(if (@($u.hints).Count) { ' - ' + ($u.hints -join ', ') } else { '' }))) }
+}
+$md.Add(''); $md.Add('## Configuration')
+$md.Add("- Copied to ``config-templates/`` ($($copied.Count) file(s)): configuration that lived inside a runtime folder. It IS part of the app. **Read each one before committing it**: the credential check is a heuristic.")
+if ($withheld.Count) { $md.Add("- **Withheld, $($withheld.Count) file(s) that look like they hold a credential.** Make a template by hand with the secret replaced by a placeholder:"); $withheld | ForEach-Object { $md.Add("  - ``$_``") } }
+if ($tooBig.Count) { $md.Add("- Too large to copy automatically ($($tooBig.Count)): " + (($tooBig | ForEach-Object { "``$_``" }) -join ', ')) }
+[IO.File]::WriteAllLines((Join-Path $OutDir 'README.md'), [string[]]$md, (New-Object Text.UTF8Encoding($false)))
+
+Write-Host ''
+Write-Host ("Runtimes: {0}   unclassified folders: {1}   config templates: {2}   withheld (credentials): {3}" -f $runtimes.Count, $uncl.Count, $copied.Count, $withheld.Count)
+foreach ($r in $runtimes) { Write-Host ("  {0,-11} {1,-12} {2,-35} {3} MB{4}" -f $r.kind, $r.version, $r.wasAt, $r.installedSizeMB, $(if (@($r.dataDirs).Count) { "   data: " + (($r.dataDirs | ForEach-Object { "$($_.path) $($_.sizeMB) MB" }) -join ', ') } else { '' })) }
+foreach ($u in $uncl) { Write-PortWarn ("UNCLASSIFIED {0} ({1} MB) {2}" -f $u.path, $u.sizeMB, ($u.hints -join ', ')) }
+Write-Host "    written to $OutDir (runtimes.json, README.md, provision.ps1, config-templates/)"
+exit 0

package/bundles/codex/.codex/skills/devops/port-to-github/scripts/Publish-PortToGitHub.ps1

@@ -27,7 +27,10 @@ param(
     [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
+    [switch]$AllowWorkflowRuns,
+    # Publish although the content policy is not met. An explicit owner exception, recorded in
+    # manifest.json; never a default.
+    [switch]$AcceptContentPolicy
 )
 
 $ErrorActionPreference = 'Stop'
@@ -44,6 +47,22 @@ $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." }
+$policyPath = Join-Path $stage 'content-policy.json'
+if (-not (Test-Path -LiteralPath $policyPath)) {
+    throw "No content-policy report. Run Test-PortContentPolicy.ps1 -Name $Name first (phase 2b)."
+}
+$policyReport = Get-Content -LiteralPath $policyPath -Raw | ConvertFrom-Json
+# The report must describe THIS stage: a clean or re-stage after the check makes it stale.
+if ((Get-Item -LiteralPath $policyPath).LastWriteTime -lt (Get-Item -LiteralPath $manifestPath).LastWriteTime) {
+    throw "content-policy.json is older than manifest.json, so it does not describe the current stage. Re-run Test-PortContentPolicy.ps1."
+}
+if (-not $policyReport.compliant) {
+    if (-not $AcceptContentPolicy) {
+        throw "Content policy not met: $($policyReport.excludedPaths) excluded path(s), $($policyReport.excludedMB) MB in history. Clean it (Invoke-PortHistoryClean.ps1), add keep rules, or pass -AcceptContentPolicy as an explicit owner exception."
+    }
+    Write-PortWarn "Publishing WITH $($policyReport.excludedPaths) excluded path(s) by explicit owner exception (-AcceptContentPolicy)."
+    $manifest | Add-Member -NotePropertyName contentPolicyException -NotePropertyValue ([pscustomobject]@{ at = (Get-Date).ToString('o'); excludedPaths = $policyReport.excludedPaths; excludedMB = $policyReport.excludedMB }) -Force
+}
 $live = @()
 if ($readiness.PSObject.Properties.Name -contains 'branchesWithGithubWorkflows') { $live = @($readiness.branchesWithGithubWorkflows) }
 if ($live.Count -gt 0 -and -not $AllowWorkflowRuns) {