@caddis/cli 0.4.18 → 0.4.20

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

@@ -0,0 +1,231 @@
+---
+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".
+---
+
+# 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 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.
+
+| Phase | Script | Changes anything outside this machine? |
+|---|---|---|
+| 1. Stage the source | `Get-PortSource.ps1` | No. The source is only read. |
+| 2. Readiness | `Test-PortReadiness.ps1` | No. |
+| 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.** |
+| 6. Retire the old host | manual, see `references/old-host.md` | **Yes, and can be destructive.** |
+
+**Stop and ask the user before phases 3, 5 and 6.** Each one is outward-facing. Say exactly
+what will be created or changed, on which host, and how to undo it.
+
+Not every port needs every phase. A folder that never had CI or a deploy host ends after
+phase 3. Say which phases apply and why, before you start.
+
+## Before you start
+
+1. **Read the project config**, if one exists: `.caddis/port-to-github.json` in the repo you are
+   working from (or `$env:PORT_TO_GITHUB_CONFIG`). It sets the GitHub `owner`, `visibility`,
+   staging folder, the name for the old remote, dependency hosts and their secrets, and
+   `projectNotes` - pointers to the project's own rules. **Read every file `projectNotes` names
+   before phase 4.** Project rules beat this skill. The shape is in `references/config.example.json`.
+2. `gh auth status` must show an account that can create repos in the owner. `git` must be able
+   to push to github.com (run `gh auth setup-git` once if not).
+3. **Find the authoritative copy.** If a folder is a clone of a server, port from the SERVER
+   URL, not the folder: the folder may lack branches the server has. Port from a folder only
+   when it is the only copy, or when it holds commits the server lacks. Phase 1 reports both
+   cases.
+
+## Phase 1 - stage the source
+
+```powershell
+$s = '<path-to-this-skill>/scripts'
+& $s/Get-PortSource.ps1 -Source <source> [-Name <repo-name>] [-IncludeUncommitted]
+```
+
+| Source | Example `-Source` |
+|---|---|
+| any git server | `https://gitea.example/org/app.git`, `git@host:org/app.git` |
+| local folder | `D:\work\app` |
+| network share | `\\fileserver\projects\app` |
+| remote box (WinRM) | `winrm://appserver01/D:/apps/app` (or `-ComputerName appserver01 -Source D:\apps\app`) |
+
+What it does, for every kind: builds `<staging>/<Name>/mirror.git` holding ONLY branches and
+tags, removes the remote so nothing can be pushed back to the source, and writes
+`manifest.json`. A folder without history becomes one import commit; `node_modules`, virtual
+envs and caches are skipped, and a `.gitignore` is written if there was none.
+
+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.
+- **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
+  the machine. Show the user the list. Re-run with `-OnSecret Exclude` only after they agree
+  those files must not be published.
+- **Dropped refs** (`refs/pull/*`, `refs/remotes/*`, notes) are expected. GitHub refuses
+  `refs/pull/*`, and pull-request discussion does not move with git anyway. If the old host's
+  PR and issue history matters, export it before phase 6.
+
+## Phase 2 - readiness
+
+```powershell
+& $s/Test-PortReadiness.ps1 -Name <repo-name>
+```
+
+**Blockers (exit 1) must be fixed before phase 3:** a file over 100 MB anywhere in history,
+Git LFS content, a likely live credential in the current tree, an empty `${{ }}` in a file
+under `.github/workflows`. A credential found in the tree must be **rotated**, not only
+deleted: history keeps it. (An empty `${{ }}` in a `.gitea/` workflow is only a warning here:
+GitHub does not read that folder, so it matters in phase 4.)
+
+**Branches that already contain `.github/workflows` run them the moment they are pushed** -
+deploy jobs included. Readiness lists those branches; publish refuses them unless you pass
+`-AllowWorkflowRuns`, which you do only after reading every such workflow with the user.
+
+**Warnings are decisions.** Go through each with the user: secret-type files in past history
+(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 3 - publish (ask first)
+
+Tell the user: the repo name, owner, visibility, branch and tag counts. Then:
+
+```powershell
+& $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
+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,
+rebuild it with `Get-PortSource.ps1 -Force`.
+
+- **Never** `git push --mirror`: it tries to push hidden refs, fails AFTER pushing the rest (so
+  a populated repo reports failure), and deletes anything on GitHub the stage lacks.
+- **An existing repo.** If one exists with history, the script refuses. Find out whether it
+  shares history with the source: for a few of its commit SHAs, `git -C mirror.git cat-file -e
+  <sha>^{commit}`. If it shares nothing (for example a snapshot someone uploaded with a fresh
+  "Initial commit"), pushing on top welds a fake ancestry in forever: save anything of value
+  from it, delete it, and re-run. Use `-AllowExisting` only when it is a genuine older copy; the
+  script then requires every GitHub branch to be an ancestor of the staged one.
+- Verify with the SHA comparison, never by counting refs or by "the push said OK".
+
+Stop here if the app has no CI and no deploy host. Otherwise continue.
+
+## Phase 4 - CI
+
+Work in a normal clone of the NEW repo, on a feature branch.
+
+```powershell
+git clone https://github.com/<owner>/<repo>.git; cd <repo>; git switch -c port/github-actions
+& $s/Convert-PortWorkflow.ps1 -AddPermissions [-SourceRef <sha>]
+```
+
+It copies `.gitea/workflows` (or `.forgejo/workflows`) to `.github/workflows`, rewrites the
+`gitea.` context to `github.`, and prints every credential line. **Leave the scripts the
+workflows call where they are** - GitHub only needs the workflow file under `.github/`.
+
+Then do by hand, one line at a time - this is the whole job, and a blanket swap breaks it:
+
+1. **Classify every credential line.** It faces ORIGIN (checkout, fetch, reset, pushing a tag
+   back to this repo) or it names a DEPENDENCY host (a package registry, a library pinned from
+   another repo or server). There is no third category.
+   - ORIGIN -> `${{ github.token }}`, username `x-access-token`. This includes an
+     `actions/checkout` that pushes tags - it is easy to miss.
+   - DEPENDENCY -> a secret valid for THAT host. `github.token` reads only the repo whose
+     workflow is running, so a library in ANOTHER GitHub repo needs its own read token.
+   One job can hold two credential pairs that serve different hosts. Change only the pair
+   that faces origin.
+2. **One Authorization header per host.** `http.<url>.extraheader` values ACCUMULATE; two for the
+   same host is an HTTP 400. `actions/checkout` persists its own header, so a step that adds
+   another for github.com must unset the checkout's for that command and restore it after.
+3. **npm and GitHub dependencies:** npm fetches a GitHub dependency over SSH even when
+   `package.json` says `https`. Set `url.https://github.com/.insteadOf=ssh://git@github.com/`
+   and `GIT_TERMINAL_PROMPT=0` so a missing credential fails in seconds instead of hanging.
+4. **Runner labels** must exist on GitHub (`runs-on:`). Self-hosted runners must be registered
+   to the org or repo, not only to the old host.
+5. **Never write `${{ }}` in any text in a workflow**, including comments inside `run:` blocks.
+6. **If a workflow was frozen** on the old host (triggers reduced to `workflow_dispatch`), pass
+   `-SourceRef` with the last commit before the freeze. A workflow built from a frozen copy
+   fires on nothing, which looks like "still queued", not like a fault.
+
+Details and the credential patterns: `references/ci-and-credentials.md`.
+
+**Validate before anything reaches `main`.** Commit the workflow files BY NAME, push the branch,
+then:
+
+```powershell
+& $s/Test-PortWorkflowParses.ps1 -Owner <owner> -Repo <repo> -Branch port/github-actions
+```
+
+An unparseable workflow produces a failed run with zero jobs even on a branch its triggers
+ignore; a valid one produces no run (or a normal run). A broken workflow on `main` leaves the
+app with no deploy path, so this check is not optional. Then open a PR and let the real jobs
+run; merging follows the repo's normal rules.
+
+## Phase 5 - cutover (ask first)
+
+Only for apps with a deploy host whose checkout pulls from the old origin. Order matters:
+
+1. `Switch-CheckoutOrigin.ps1 -Mode Inspect` on each host. Record what it prints.
+2. **Tell the user** the host, path, old and new URL, and the rollback command.
+3. Switch:
+   ```powershell
+   & $s/Switch-CheckoutOrigin.ps1 -Path D:\apps\app [-ComputerName appserver01] -Mode Switch `
+       -NewUrl https://github.com/<owner>/<repo>.git -VerifyWithGhToken
+   ```
+   It records the old URL first, keeps it as a second remote, fetches, and requires the
+   checkout's HEAD to be on a GitHub branch. On failure it restores the old origin itself.
+   `-VerifyWithGhToken` lends your gh token to that one fetch, in memory only, because a deploy
+   host normally has no GitHub credential of its own (CI supplies one per run).
+4. **Stop the old host from deploying** (disable its deploy job) only AFTER the first GitHub
+   deploy is green. Two schedulers on one checkout have no lock between them.
+5. **Verify the deploy by an artefact changing** - a built bundle's hash or file time - never by
+   an HTTP 200 or a version endpoint alone. Both pass when a new backend serves an old frontend.
+
+Rollback, at any point before phase 6:
+
+```powershell
+& $s/Switch-CheckoutOrigin.ps1 -Path D:\apps\app [-ComputerName appserver01] -Mode Rollback
+```
+
+Also repoint developer checkouts the same way (`-Mode Switch` without `-VerifyWithGhToken`), so
+`git push` goes to GitHub. Keep the old remote; it is the local rollback.
+
+## Phase 6 - retire the old host (ask first)
+
+Read `references/old-host.md`. The short version:
+
+- Prove nothing is lost first:
+  `& $s/Compare-PortRefs.ps1 -Left <old-url> -Right <github-url> -Mode LeftInRight` must exit 0.
+  Push any ref that exists only on the old host before you continue.
+- Prefer a **read-only pull mirror** of GitHub on the old host (Actions off) over deleting it:
+  anything still pinned to the old URL keeps working. Never a push mirror from CI.
+- Anything that still pins a dependency from the old host keeps the old host alive. Find those
+  pins before retiring it.
+
+## Report
+
+End with a short table per app: source kind, branches and tags ported (SHA-verified yes/no),
+warnings accepted and by whom, CI state, cutover state and rollback command, what is left.
+Say which phases were skipped and why.
+
+## Rules that apply to every phase
+
+- Stage files BY NAME. The only `git add -A` is inside the scripts, on fresh throwaway trees.
+- A check that cannot fail is not a check. Every script here exits non-zero on the failure it
+  exists for; do not pipe it to `Out-Null` or read only its last line.
+- Audit the default branch on the SERVER (`origin/main`), never a working tree that may sit on
+  an old feature branch.
+- Code that runs on a remote box runs under Windows PowerShell 5.1. There, with
+  `$ErrorActionPreference='Stop'`, a native command's stderr is a terminating error even with
+  `2>$null`. Use `'Continue'` and judge native commands by `$LASTEXITCODE`.
+- One variable at a time. When a whole batch fails the same way, change one thing and retry
+  one item before re-reading the request.

package/bundles/codex/.codex/skills/devops/port-to-github/references/ci-and-credentials.md

@@ -0,0 +1,66 @@
+# CI and credentials after a port
+
+Every item here broke a real deploy at least once.
+
+## The two kinds of credential
+
+| Faces | Examples | On GitHub |
+|---|---|---|
+| ORIGIN - this repo | `actions/checkout`, a deploy script's `git fetch`/`reset`, pushing a version tag back | `${{ github.token }}`, username `x-access-token`. Needs `permissions: contents: write` to push. Nothing to store or rotate. |
+| DEPENDENCY - another host or repo | a library pinned `git+https://host/org/lib.git@v1`, a private npm/PyPI registry, a Git server that stays behind | A secret that can read THAT host. `github.token` cannot read a different repo, even in the same org. |
+
+Choose the credential **per host**, from the host named in the pin, never from where the app is
+hosted. When a pin moves from the old server to GitHub, its credential must move with it in the
+same commit; when an app moves but its pins do not, the old credential must stay.
+
+A deploy script that builds its auth header from `git remote get-url origin` needs NO change
+for the origin half: repointing origin (phase 5) is the whole cutover. It DOES need a change if
+it also uses that origin-derived credential for dependency clones - the moment origin is
+GitHub and the dependency is not, that pairing is wrong.
+
+## Injecting a credential for a child process (pip, npm)
+
+`GIT_CONFIG_*` environment entries (git 2.31+) are inherited by every git a tool spawns:
+
+```yaml
+env:
+  GIT_CONFIG_COUNT: '2'
+  GIT_CONFIG_KEY_0: http.https://github.com/.extraheader
+  GIT_CONFIG_VALUE_0: AUTHORIZATION: basic <base64 of x-access-token:TOKEN>
+  GIT_CONFIG_KEY_1: http.https://old-host.example/.extraheader
+  GIT_CONFIG_VALUE_1: AUTHORIZATION: basic <base64 of user:OLD_HOST_TOKEN>
+```
+
+Add a new entry and increment the count. Never replace entry 0 when another host still needs
+it. Build the base64 in a script step from `env:`; never put a token in a URL - it lands in
+lockfiles and logs.
+
+## Traps
+
+- **Header accumulation.** `http.<url>.extraheader` never overrides; git sends every matching
+  one. `actions/checkout` persists one in `.git/config`. A second for the same host -> HTTP 400
+  `Duplicate header: "Authorization"`. Unset the checkout's entry for the one command that
+  needs a different credential, then restore it; otherwise every later step loses its auth.
+- **`git config --local` outside a repo fails.** A runner's temp working directory is not a
+  repository. Check `git rev-parse --is-inside-work-tree` first.
+- **npm uses SSH for GitHub deps** despite `https` in `package.json` and the lockfile. Add
+  `url.https://github.com/.insteadOf ssh://git@github.com/`. Also make sure the lockfile's
+  `resolved` URLs say `git+https`, not `git+ssh`.
+- **A cache hit is not proof of credentials.** A warm npm or pip cache skips the authenticated
+  fetch entirely. Prove a new credential with a fresh install (cleared cache, empty `HOME`, no
+  credential helper).
+- **Windows PowerShell 5.1 runners.** With `$ErrorActionPreference='Stop'`, anything a native
+  exe writes to stderr becomes a terminating error, and `2>$null` does not prevent it. Use
+  `'Continue'` in the step, `2>&1 | Out-Null` to silence, and judge by `$LASTEXITCODE`.
+- **A step whose last native command is EXPECTED to fail** (a negative test) must end with
+  `exit 0`, or the step is red after printing its pass.
+- **Required checks.** A job skipped by a path filter at the TRIGGER never reports, so making it
+  a required check blocks every PR that does not touch those paths. A job skipped by `if:` counts
+  as passed. Renaming a job renames its check context and silently breaks a branch rule.
+- **`concurrency: cancel-in-progress`** cancels a PR's running jobs when you push again. A
+  `cancelled` job or a PR with no runs is often this, not a fault. Re-check against the new
+  head SHA.
+- **Deploy scripts may run from the deploy checkout**, not from the commit being deployed. If the
+  workflow syncs that checkout to the target commit before calling the script, a script change
+  takes effect on the first deploy; if it does not, it takes effect on the NEXT deploy. Check
+  which before predicting.

package/bundles/codex/.codex/skills/devops/port-to-github/references/config.example.json

@@ -0,0 +1,18 @@
+{
+  "_comment": "Copy to .caddis/port-to-github.json in the repo you run the port from. Every field is optional.",
+  "owner": "example-org",
+  "visibility": "private",
+  "stagingRoot": "%TEMP%\\port-to-github",
+  "oldRemoteName": "gitea",
+  "dependencyHosts": [
+    { "host": "github.com", "username": "x-access-token", "secret": "ORG_READ_TOKEN", "note": "libraries in other repos of the org" },
+    { "host": "git.example.internal", "username": "ci-bot", "secret": "OLD_HOST_READ_TOKEN", "note": "stays until nothing pins from it" }
+  ],
+  "deployHosts": [
+    { "computerName": "appserver01", "checkoutRoot": "D:\\apps" }
+  ],
+  "projectNotes": [
+    "AGENTS.md - the project's own rules; they override this skill",
+    "docs/runbooks/<your-migration-runbook>.md"
+  ]
+}

package/bundles/codex/.codex/skills/devops/port-to-github/references/old-host.md

@@ -0,0 +1,61 @@
+# Retiring the old host
+
+Only after: the app is on GitHub, SHA-verified, and its first GitHub deploy was green and
+verified by an artefact changing.
+
+## 1. Prove nothing is lost
+
+```powershell
+& <skill>/scripts/Compare-PortRefs.ps1 -Left <old-url> -Right https://github.com/<owner>/<repo>.git `
+    -Mode LeftInRight -LeftLabel old -RightLabel github
+```
+
+Exit 0 means every branch and tag on the old host exists on GitHub with the same SHA. If not,
+push the missing refs to GitHub first (from a fresh `git clone --mirror` of the old host, with
+an explicit refspec for just those refs) and run it again. Release tags pushed by the old CI
+after the port are the usual stragglers.
+
+## 2. Find what still depends on the old host
+
+Search every consumer's default branch (not working trees) for the old host name: dependency
+pins, registry config, CI steps, deploy scripts. Anything found keeps the old host alive, and
+keeps a credential for it alive.
+
+## 3. Choose: read-only mirror, archive, or delete
+
+| Option | When | Cost |
+|---|---|---|
+| **Read-only pull mirror of GitHub** (Actions OFF) | Something still pins from the old URL, or you want a live fallback | The old host keeps running; a mirror that stops pulling goes stale silently |
+| Archive (read-only, no sync) | Nothing depends on it; you want the old PR/issue history browsable | A frozen snapshot that drifts from day one |
+| Delete | Nothing depends on it and its history is exported | Irreversible |
+
+**Never a push mirror driven by CI.** A job pushing into a host that then runs CI on what
+arrives has caused a full outage: tests failed, deploy was skipped (not failed), the push guard
+only checked `failure`, and it pushed a change disabling the old deploy - leaving no deploy path
+anywhere. A pull mirror with Actions disabled cannot do that.
+
+## 4. Converting a Gitea repo into a pull mirror
+
+An existing Gitea repo cannot be converted in place. It must be deleted and recreated as a
+mirror under the same path, which **destroys its pull requests and issues** - export them first
+(API: `/repos/{owner}/{repo}/pulls?state=all`, `/issues?state=all`, comments per item).
+
+1. Run step 1 again immediately before, and export PRs/issues.
+2. `DELETE /api/v1/repos/{owner}/{repo}`.
+3. **Verify the delete on BOTH halves: the API returns 404 AND the repository directory is gone
+   on disk.** Gitea can remove the database row and fail on disk (a locked pack file). The next
+   create then returns 500 while still making an EMPTY mirror row, on which `mirror-sync`
+   returns 400. The Gitea log names the locked file; nothing else does.
+4. `POST /api/v1/repos/migrate` with `mirror: true`, the GitHub clone URL, and a GitHub read
+   token (`auth_token`). Then disable Actions on it (`has_actions: false`).
+5. Verify by refs, not by existence: `Compare-PortRefs.ps1 -Left <github> -Right <gitea> -Mode Equal`.
+6. If something pins from the mirror, prove it: clone the exact pinned tag from the mirror.
+
+## 5. Watching a mirror
+
+A pull mirror syncs on an interval (Gitea default 8h). A mirror behind GitHub is either LAGGING
+(the GitHub commit is newer than the mirror's last pull - normal) or STALE (the commit was there
+at the last pull and still did not arrive - the stored credential probably expired). Decide
+which by comparing the GitHub commit time with the mirror's last-update time before you touch
+any credential. `POST /repos/{owner}/{repo}/mirror-sync` forces a pull: an immediate match means
+it was lag.

package/bundles/codex/.codex/skills/devops/port-to-github/scripts/Compare-PortRefs.ps1

@@ -0,0 +1,68 @@
+<#
+.SYNOPSIS
+  Compare branches and tags between two git locations by SHA. The only honest "did it copy" check.
+
+.DESCRIPTION
+  -Left and -Right can each be a URL, a local path, a UNC path or a bare repository.
+  Uses git ls-remote, so nothing is fetched or changed.
+
+  Modes:
+    Equal           every head and tag matches on both sides (after a push)
+    LeftInRight     every Left ref exists in Right with the same SHA; Right may have more
+                    (before destroying an old host: nothing on the old host may be lost)
+
+  Exit 0 when the mode holds, 1 when it does not, and the differing refs are printed.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$Left,
+    [Parameter(Mandatory)][string]$Right,
+    [ValidateSet('Equal', 'LeftInRight')][string]$Mode = 'Equal',
+    [string]$LeftLabel = 'left',
+    [string]$RightLabel = 'right',
+    [switch]$PassThru
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'PortCommon.ps1')
+
+function Get-Refs([string]$Where) {
+    $lines = Invoke-PortGit @('ls-remote', '--heads', '--tags', $Where)
+    $map = @{}
+    foreach ($l in $lines) {
+        if (-not $l) { continue }
+        $sha, $ref = $l -split "`t", 2
+        # An annotated tag shows twice: the tag object and the peeled commit (^{}). Compare the
+        # tag object; the peeled line is derived from it.
+        if ($ref -like '*^{}') { continue }
+        $map[$ref] = $sha
+    }
+    return $map
+}
+
+$l = Get-Refs $Left
+$r = Get-Refs $Right
+
+$onlyLeft = @($l.Keys | Where-Object { -not $r.ContainsKey($_) } | Sort-Object)
+$onlyRight = @($r.Keys | Where-Object { -not $l.ContainsKey($_) } | Sort-Object)
+$differ = @($l.Keys | Where-Object { $r.ContainsKey($_) -and $r[$_] -ne $l[$_] } | Sort-Object)
+
+$ok = ($onlyLeft.Count -eq 0 -and $differ.Count -eq 0)
+if ($Mode -eq 'Equal') { $ok = $ok -and ($onlyRight.Count -eq 0) }
+
+Write-Host ("{0}: {1} refs   {2}: {3} refs   only-{0}: {4}   only-{2}: {5}   differ: {6}" -f $LeftLabel, $l.Count, $RightLabel, $r.Count, $onlyLeft.Count, $onlyRight.Count, $differ.Count)
+foreach ($x in $onlyLeft) { Write-Host "  only in ${LeftLabel}:  $x" }
+if ($Mode -eq 'Equal') { foreach ($x in $onlyRight) { Write-Host "  only in ${RightLabel}: $x" } }
+foreach ($x in $differ) { Write-Host "  differs:        $x  $($l[$x].Substring(0,12)) vs $($r[$x].Substring(0,12))" }
+
+if ($l.Count -eq 0) {
+    Write-PortFail "$LeftLabel has no refs at all. An empty side cannot prove anything."
+    $ok = $false
+}
+if ($ok) { Write-PortOk "Refs agree ($Mode)." } else { Write-PortFail "Refs do NOT agree ($Mode)." }
+
+if ($PassThru) {
+    [pscustomobject]@{ Ok = $ok; OnlyLeft = $onlyLeft; OnlyRight = $onlyRight; Differ = $differ; LeftCount = $l.Count; RightCount = $r.Count }
+}
+if (-not $ok) { exit 1 }
+exit 0

package/bundles/codex/.codex/skills/devops/port-to-github/scripts/Convert-PortWorkflow.ps1

@@ -0,0 +1,92 @@
+<#
+.SYNOPSIS
+  Copy Gitea/Forgejo Actions workflows to .github/workflows in a working clone, and lint them.
+
+.DESCRIPTION
+  Run inside a normal (non-bare) clone of the NEW GitHub repository, on a feature branch.
+  - Reads each workflow from -SourceRef (default HEAD), NOT from the working tree, so you can
+    point it at the last commit before a workflow was frozen (e.g. -SourceRef <sha>).
+  - Rewrites the `gitea.` expression context to `github.` (same meaning on both).
+  - Optionally adds top-level `permissions: contents: write` (needed to push tags).
+  - Never touches scripts the workflows call. GitHub only needs the WORKFLOW under
+    .github/workflows; leaving .gitea/scripts where it is keeps the diff small.
+  - Never stages or commits. It prints the files it wrote so you can review and add them by name.
+
+  Exit 1 if any written workflow still contains an empty expression.
+#>
+[CmdletBinding()]
+param(
+    [string]$RepoPath = '.',
+    [string]$From,
+    [string]$SourceRef = 'HEAD',
+    [switch]$AddPermissions,
+    [switch]$Force
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'PortCommon.ps1')
+
+$RepoPath = (Resolve-Path -LiteralPath $RepoPath).Path
+if (-not $From) {
+    foreach ($c in '.gitea/workflows', '.forgejo/workflows') {
+        $ls = Invoke-PortGit -AllowFailure @('-C', $RepoPath, 'ls-tree', '--name-only', "${SourceRef}:$c")
+        if ($ls.ExitCode -eq 0 -and ($ls.Output -join '')) { $From = $c; break }
+    }
+}
+if (-not $From) { throw "No .gitea/workflows or .forgejo/workflows at $SourceRef. Pass -From." }
+
+$names = @(Invoke-PortGit @('-C', $RepoPath, 'ls-tree', '--name-only', "${SourceRef}:$From") | Where-Object { $_ -match '\.ya?ml$' })
+if ($names.Count -eq 0) { throw "No workflow files in $From at $SourceRef." }
+
+$target = Join-Path $RepoPath '.github/workflows'
+New-Item -ItemType Directory -Force -Path $target | Out-Null
+$written = @()
+$bad = 0
+
+foreach ($n in $names) {
+    $dest = Join-Path $target $n
+    if ((Test-Path -LiteralPath $dest) -and -not $Force) { Write-PortWarn "$n already exists in .github/workflows. Skipped (use -Force)."; continue }
+    $text = (Invoke-PortGit @('-C', $RepoPath, 'show', "${SourceRef}:$From/$n")) -join "`n"
+
+    $ctx = 0
+    foreach ($m in [regex]::Matches($text, '\$\{\{[^}]*\}\}')) { $ctx += ([regex]::Matches($m.Value, '\bgitea\.')).Count }
+    $text = [regex]::Replace($text, '(\$\{\{[^}]*?)\bgitea\.', '$1github.')
+    # Repeat until no gitea. context remains inside any expression (several per expression).
+    while ([regex]::IsMatch($text, '\$\{\{[^}]*?\bgitea\.')) { $text = [regex]::Replace($text, '(\$\{\{[^}]*?)\bgitea\.', '$1github.') }
+
+    if ($AddPermissions -and $text -notmatch '(?m)^permissions:') {
+        # Instance Replace with a real count. The static [regex]::Replace(s, p, r, 1) binds the 1 to
+        # RegexOptions.IgnoreCase and replaces EVERY match.
+        if ($text -match '(?m)^jobs:') { $text = ([regex]'(?m)^jobs:').Replace($text, "permissions:`n  contents: write`n`njobs:", 1) }
+    }
+
+    if ($text -match '(?m)^on:\s*(\[\s*)?workflow_dispatch' -and $text -notmatch '(?m)^\s+(push|pull_request)\s*:') {
+        Write-PortWarn "$n triggers only on workflow_dispatch at $SourceRef. That is what a FROZEN workflow looks like. Re-run with -SourceRef set to the last commit before it was frozen."
+    }
+
+    [IO.File]::WriteAllText($dest, ($text -replace "`r?`n", "`n"), (New-Object Text.UTF8Encoding($false)))
+    $written += ".github/workflows/$n"
+
+    $lines = $text -split "`n"
+    $empty = @()
+    for ($i = 0; $i -lt $lines.Count; $i++) { if ($lines[$i] -match '\$\{\{\s*\}\}') { $empty += ($i + 1) } }
+    if ($empty.Count -gt 0) {
+        $bad++
+        Write-PortFail "$n line(s) $($empty -join ', '): empty `${{ }}. GitHub rejects the whole file. Reword the text (a comment inside run: is still scanned)."
+    }
+    Write-PortOk "$n -> .github/workflows/$n (gitea. context rewritten: $ctx)"
+    $creds = @()
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        if ($lines[$i] -match 'secrets\.|github\.token|(?i)token\s*:|_TOKEN\b|_USER\b|PASSWORD') { $creds += ("    {0}: {1}" -f ($i + 1), $lines[$i].Trim()) }
+    }
+    if ($creds.Count -gt 0) {
+        Write-Host "  Credential lines - decide EACH one: ORIGIN-facing (this repo: fetch, checkout, tag push) -> `${{ github.token }} with user x-access-token; DEPENDENCY host -> a secret valid for THAT host."
+        $creds | ForEach-Object { Write-Host $_ }
+    }
+}
+
+Write-Host ''
+Write-Host 'Written (review, then git add each file BY NAME):'
+$written | ForEach-Object { Write-Host "  $_" }
+if ($bad -gt 0) { exit 1 }
+exit 0