@caddis/cli 0.4.22 → 0.4.23

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

@@ -0,0 +1,218 @@
+<#
+.SYNOPSIS
+  Check a staged repository against the source-only content policy, over the tips AND all history.
+
+.DESCRIPTION
+  The policy: a repository holds application code, configuration and templates, migration
+  SCRIPTS, tests, and the scripts/manifests that rebuild the environment. It does NOT hold:
+
+    runtime      a runtime or server distribution (MariaDB, PHP, JDK, Node, Python, Apache...)
+    binary       compiled or packaged files (.exe .dll .so .jar .msi, archives)
+    db-data      database data files (ibdata1, *.ibd, *.frm, *.mdf, SQLite files, dumps)
+    data-export  data files above the size threshold (.csv .xlsx .json .xml .sql ...), or any
+                 data file under a backups/dumps/exports folder
+    dependency   installed dependencies (node_modules, vendor, .venv, site-packages)
+    backup       editor and copy backups (*.bak, *.orig, *.old, *~)
+
+  Large files that match no rule are reported as 'large-review' (a decision, not a violation).
+
+  .gitignore does not remove a file that was committed before it: every excluded path is
+  checked in ALL history, not only in the current files.
+
+  Reads <staging>\<Name>\mirror.git. Changes nothing. Writes content-policy.json next to it.
+  Exit 0: compliant. Exit 1: at least one excluded path exists somewhere in history.
+
+  Project overrides (optional) in the config file, key "contentPolicy":
+    { "keep": ["regex", ...], "exclude": ["regex", ...], "dataThresholdMB": 5, "largeMB": 10 }
+  Regexes match the repository path (forward slashes).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$Name,
+    [string]$StagingRoot,
+    [string]$ConfigPath,
+    [double]$DataThresholdMB,
+    [double]$LargeMB,
+    # Print every finding, not only the per-folder summary.
+    [switch]$Detail
+)
+
+$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'
+if (-not (Test-Path -LiteralPath $mirror)) { throw "No staged mirror at $mirror. Run Get-PortSource.ps1 first." }
+$manifest = Get-Content -LiteralPath (Join-Path $stage 'manifest.json') -Raw | ConvertFrom-Json
+$branch = $manifest.defaultBranch
+
+$policy = Get-PortConfigValue $config 'contentPolicy' $null
+$keepRx = @(); $extraExcludeRx = @()
+if ($policy) {
+    if ($policy.PSObject.Properties.Name -contains 'keep') { $keepRx = @($policy.keep) }
+    if ($policy.PSObject.Properties.Name -contains 'exclude') { $extraExcludeRx = @($policy.exclude) }
+    if (-not $DataThresholdMB -and $policy.PSObject.Properties.Name -contains 'dataThresholdMB') { $DataThresholdMB = [double]$policy.dataThresholdMB }
+    if (-not $LargeMB -and $policy.PSObject.Properties.Name -contains 'largeMB') { $LargeMB = [double]$policy.largeMB }
+}
+if (-not $DataThresholdMB) { $DataThresholdMB = 5 }
+if (-not $LargeMB) { $LargeMB = 10 }
+$dataBytes = [int64]($DataThresholdMB * 1MB)
+$largeBytes = [int64]($LargeMB * 1MB)
+
+# A runtime folder is the runtime's NAME, optionally followed by a version or platform tag
+# (php-8.3.33, jdk-17.0.2, node-v20.11.0-win-x64, apache24). Not any folder that merely STARTS
+# with one: redis-migrations/ or apache-poi-wrapper/ are source.
+$ver = '([-_ ]?v?\d[\w.]*(-(win|linux|x64|x86|amd64|arm64)[\w.-]*)?)?'
+$runtimeDirRx = "(?i)^(mariadb|mysql|mysql-server|php|jdk|jre|openjdk|java|python|python-embed|nodejs|node|apache|httpd|nginx|tomcat|apache-tomcat|redis|postgres|postgresql|pgsql|erlang|ruby|dotnet|go)$ver$"
+$runtimeBinRx = '(?i)^(mariadbd|mysqld|mariadb|mysql|php|php-cgi|node|python|pythonw|java|javaw|httpd|nginx|redis-server|postgres|pg_ctl|erl|ruby|dotnet)\.exe$'
+$dependencyDirRx = '(?i)^(node_modules|vendor|\.venv|venv|site-packages|bower_components|\.yarn|jspm_packages)$'
+$binaryExtRx = '(?i)\.(exe|dll|so|dylib|msi|msix|bin|iso|img|jar|war|ear|class|pyc|pdb|lib|a|o|obj|zip|7z|tar|gz|tgz|rar|bz2|xz|cab|nupkg|whl|deb|rpm)$'
+$dbDataRx = '(?i)(^|/)(ibdata\d*|ib_logfile\d*|ib_buffer_pool|aria_log[\w.]*|undo\d+)$|\.(ibd|frm|myd|myi|mdf|ldf|ndf|sqlite3?|db3|dmp)$'
+$backupRx = '(?i)(\.(bak|orig|old|swp)|~)$'
+$dataExtRx = '(?i)\.(csv|tsv|xlsx|xlsm|xlsb|xls|ods|parquet|avro|orc|jsonl|ndjson|json|xml|sql|dat|txt|log)$'
+$dataDirRx = '(?i)^(backups?|dumps?|exports?|snapshots?|data-?dumps?)$'
+
+function Get-Category([string]$Path, [int64]$Bytes) {
+    foreach ($rx in $keepRx) { if ($Path -match $rx) { return $null } }
+    foreach ($rx in $extraExcludeRx) { if ($Path -match $rx) { return 'project-exclude' } }
+    $parts = $Path -split '/'
+    $dirs = if ($parts.Count -gt 1) { $parts[0..($parts.Count - 2)] } else { @() }
+    $leaf = $parts[-1]
+    foreach ($d in $dirs) { if ($d -match $runtimeDirRx) { return 'runtime' } }
+    if ($leaf -match $runtimeBinRx) { return 'runtime' }
+    foreach ($d in $dirs) { if ($d -match $dependencyDirRx) { return 'dependency' } }
+    if ($Path -match $dbDataRx) { return 'db-data' }
+    if ($leaf -match $backupRx) { return 'backup' }
+    if ($leaf -match $binaryExtRx) { return 'binary' }
+    if ($leaf -match $dataExtRx) {
+        # Under a backups/dumps folder any data file is excluded, but a plain note (.txt/.md) is not data.
+        if ($leaf -notmatch '(?i)\.(txt|md)$') { foreach ($d in $dirs) { if ($d -match $dataDirRx) { return 'data-export' } } }
+        # Migration SCRIPTS stay by policy. A large .sql under migration(s)/ may be a script or a
+        # data load, so it is a decision, not an automatic exclusion. Data FILES there (csv, json,
+        # xlsx) are still data.
+        if ($leaf -match '(?i)\.sql$' -and ($dirs | Where-Object { $_ -match '(?i)^migrations?$' })) {
+            if ($Bytes -ge $largeBytes -or $Bytes -ge $dataBytes) { return 'large-review' }
+            return $null
+        }
+        if ($Bytes -ge $dataBytes) { return 'data-export' }
+    }
+    if ($Bytes -ge $largeBytes) { return 'large-review' }
+    return $null
+}
+
+function MGit([string[]]$a) { Invoke-PortGit (@('-C', $mirror) + $a) }
+
+# ---- every blob in history, with every path it ever had ----------------------------------
+Write-PortStep 'Reading every path and blob in history'
+$pathsBySha = @{}
+$submodules = New-Object System.Collections.Generic.HashSet[string]
+function Add-PathForSha([string]$sha, [string]$p) {
+    if (-not $pathsBySha.ContainsKey($sha)) { $pathsBySha[$sha] = New-Object System.Collections.Generic.HashSet[string] }
+    [void]$pathsBySha[$sha].Add($p)
+}
+# EVERY path a blob was ever written to. rev-list --objects names each blob only ONCE, by the
+# first path it meets, so identical content at a second path was invisible (found by the
+# dogfood: a 3-byte test image at two paths survived a clean). log --raw lists every add or
+# change, per commit, including merges (-m) and root commits.
+foreach ($l in (MGit @('-c', 'core.quotePath=false', 'log', '--all', '--raw', '--no-abbrev', '--no-renames', '-m', '--root', '--format=', '--diff-filter=AMT'))) {
+    if (-not $l -or $l[0] -ne ':') { continue }
+    $meta, $p = $l -split "`t", 2
+    $f = $meta -split ' '
+    if ($f.Count -lt 4 -or -not $p -or $f[3] -match '^0+$') { continue }
+    # Mode 160000 is a submodule: its "blob" is a commit in ANOTHER repository, invisible to a
+    # size scan. Record it, so a runtime vendored as a submodule cannot pass unnoticed.
+    if ($f[1] -eq '160000') { [void]$submodules.Add($p); continue }
+    Add-PathForSha $f[3] $p
+}
+# Safety net: anything reachable that the log did not show.
+foreach ($l in (MGit @('rev-list', '--objects', '--all'))) {
+    $sha, $p = $l -split ' ', 2
+    if ($p -and -not $pathsBySha.ContainsKey($sha)) { Add-PathForSha $sha $p }
+}
+$sizeBySha = @{}
+foreach ($l in (MGit @('cat-file', '--batch-all-objects', '--batch-check=%(objecttype) %(objectname) %(objectsize)'))) {
+    $t, $o, $s = $l -split ' '
+    if ($t -eq 'blob' -and $pathsBySha.ContainsKey($o)) { $sizeBySha[$o] = [int64]$s }
+}
+
+# Aggregate per path: largest version, number of versions.
+$byPath = @{}
+foreach ($sha in $sizeBySha.Keys) {
+    foreach ($p in $pathsBySha[$sha]) {
+        if (-not $byPath.ContainsKey($p)) { $byPath[$p] = [pscustomobject]@{ path = $p; maxBytes = [int64]0; versions = 0 } }
+        $e = $byPath[$p]; $e.versions++
+        if ($sizeBySha[$sha] -gt $e.maxBytes) { $e.maxBytes = $sizeBySha[$sha] }
+    }
+}
+
+$tipFiles = @{}
+foreach ($l in (MGit @('-c', 'core.quotePath=false', 'ls-tree', '-r', '--name-only', $branch))) { $tipFiles[$l] = $true }
+
+# ---- classify ----------------------------------------------------------------------------------
+$findings = New-Object System.Collections.Generic.List[object]
+foreach ($e in $byPath.Values) {
+    $cat = Get-Category $e.path $e.maxBytes
+    if (-not $cat) { continue }
+    $findings.Add([pscustomobject]@{
+            path = $e.path; category = $cat; maxBytes = $e.maxBytes; versions = $e.versions
+            inDefaultBranch = [bool]$tipFiles[$e.path]
+            action = if ($cat -eq 'large-review') { 'review' } else { 'exclude' }
+        })
+}
+foreach ($sm in $submodules) {
+    $findings.Add([pscustomobject]@{ path = $sm; category = 'submodule'; maxBytes = [int64]0; versions = 1; inDefaultBranch = [bool]$tipFiles[$sm]; action = 'review' })
+}
+$exclude = @($findings | Where-Object { $_.action -eq 'exclude' })
+$review = @($findings | Where-Object { $_.action -eq 'review' })
+
+# Group by top two path segments so a 3,000-file vendored runtime reads as one line.
+# Group by folder, at most 4 levels deep, so one vendored runtime reads as one line and a
+# data folder deep in an app is still named precisely.
+function Get-Group([string]$p) { $s = $p -split '/'; if ($s.Count -le 1) { return $p }; $d = $s[0..([math]::Min(3, $s.Count - 2))]; ($d -join '/') + '/' }
+$groups = @($findings | Group-Object { "$($_.category)|$(Get-Group $_.path)" } | ForEach-Object {
+        $cat, $grp = $_.Name -split '\|', 2
+        [pscustomobject]@{
+            category = $cat; group = $grp; files = $_.Count
+            historyMB = [math]::Round((($_.Group | Measure-Object maxBytes -Sum).Sum) / 1MB, 1)
+            inDefaultBranch = @($_.Group | Where-Object { $_.inDefaultBranch }).Count
+        }
+    } | Sort-Object historyMB -Descending)
+
+$totalBytes = [int64]0; foreach ($v in $sizeBySha.Values) { $totalBytes += $v }
+# Count each blob once, even when it sits at several excluded paths (a per-path sum can exceed
+# the whole history). Plain loops: Measure-Object on NO input has no .Sum under strict mode.
+$exPaths = New-Object System.Collections.Generic.HashSet[string]
+foreach ($x in $exclude) { [void]$exPaths.Add($x.path) }
+$exBytes = [int64]0
+foreach ($sha in $sizeBySha.Keys) { foreach ($p in $pathsBySha[$sha]) { if ($exPaths.Contains($p)) { $exBytes += $sizeBySha[$sha]; break } } }
+$report = [ordered]@{
+    name = $Name; defaultBranch = $branch; checkedAt = (Get-Date).ToString('o')
+    thresholds = [ordered]@{ dataThresholdMB = $DataThresholdMB; largeMB = $LargeMB }
+    historyBlobMB = [math]::Round($totalBytes / 1MB, 1)
+    excludedPaths = $exclude.Count; excludedMB = [math]::Round($exBytes / 1MB, 1)
+    reviewPaths = $review.Count
+    compliant = ($exclude.Count -eq 0)
+    groups = $groups
+    findings = @($findings | Sort-Object maxBytes -Descending)
+}
+ConvertTo-PortJsonFile $report (Join-Path $stage 'content-policy.json')
+# Plain path list, one per line, for Invoke-PortHistoryClean.ps1 and for .gitignore review.
+Set-Content -LiteralPath (Join-Path $stage 'content-policy-exclude.txt') -Value @($exclude | Sort-Object path | ForEach-Object { $_.path }) -Encoding UTF8
+
+Write-Host ''
+Write-Host ("Content policy for {0}: {1} excluded path(s), {2} MB of history; {3} path(s) to review. History holds {4} MB of blobs in total." -f $Name, $exclude.Count, $report.excludedMB, $review.Count, $report.historyBlobMB)
+if ($groups.Count -gt 0) {
+    Write-Host ''
+    Write-Host ('{0,-13} {1,-55} {2,7} {3,10} {4}' -f 'category', 'where', 'files', 'MB', 'in default branch')
+    foreach ($g in $groups) { Write-Host ('{0,-13} {1,-55} {2,7} {3,10} {4}' -f $g.category, $g.group, $g.files, $g.historyMB, $g.inDefaultBranch) }
+}
+if ($Detail) { $findings | Sort-Object maxBytes -Descending | ForEach-Object { Write-Host ('  {0,-13} {1,9:N0} KB  {2}' -f $_.category, ($_.maxBytes / 1KB), $_.path) } }
+Write-Host "    report: $(Join-Path $stage 'content-policy.json')"
+Write-Host "    exclude list: $(Join-Path $stage 'content-policy-exclude.txt')"
+if ($exclude.Count -gt 0) {
+    Write-PortWarn 'Not compliant. Decide per group: keep (add a "keep" regex to contentPolicy), or remove from history with Invoke-PortHistoryClean.ps1. Adding a path to .gitignore does NOT remove it from history.'
+    exit 1
+}
+Write-PortOk 'Compliant: no excluded content anywhere in history.'
+exit 0

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