dsh-plugin-cicd 0.0.0-stage → 0.5.0

package/lib/config-store.mjs

@@ -0,0 +1,159 @@
+/**
+ * The managed repository list: parsing, validation, and one atomic writer.
+ *
+ * Two callers own this file's format — the panel's HTTP routes and
+ * `scripts/configure.mjs` — and they must not drift: a list the script writes has
+ * to be a list the Host reads, byte for byte, with the same rules about what a
+ * repository name may look like. So the rules live here once.
+ *
+ * The parse is deliberately tolerant and the write is deliberately strict. The
+ * Host must never fail to start because a file is malformed (it reports the
+ * problem instead), while a write must refuse anything it would later have to
+ * quietly drop.
+ *
+ * @module dsh-plugin-cicd/lib/config-store
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { isAbsolute, dirname } from 'node:path'
+import { normalizeBvid } from './bilibili.mjs'
+
+/** Upper bound on registered repositories, so a runaway file cannot hurt startup. */
+export const MAX_REPOS = 40
+
+/**
+ * A repository name is passed to `gh` as one argv element with no shell in
+ * between, so this shape check is not cosmetic: it is what keeps `--help` or a
+ * flag-looking string from being read as an option.
+ */
+export const SLUG = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+export const SLUG_WITH_OWNER = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+/** Trim a value that should be a non-empty string, or return the fallback. */
+function text(value, fallback = '') {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : fallback
+}
+
+/**
+ * Normalize one entry's Bilibili binding.
+ *
+ * The binding says which video's comment section carries this repository's
+ * update notes. Its shape is checked here — where the file is parsed — for the
+ * same reason a repository name is: a value this plugin cannot act on must not
+ * travel further as if it could. A malformed BV id becomes "no binding", which
+ * the panel shows as 未绑定 rather than as a comment posted to the wrong video.
+ *
+ * @param {unknown} value - `entry.bilibili`.
+ * @returns {{bvid: string, auto: boolean}|null} the normalized binding, or null.
+ */
+export function normalizeBinding(value) {
+  if (value === null || typeof value !== 'object') return null
+  const bvid = normalizeBvid(value.bvid ?? value.bv)
+  if (bvid === null) return null
+  return { bvid, auto: value.auto !== false }
+}
+
+/**
+ * Normalize one entry, accepting both shapes a person would naturally write:
+ * `dsh-plugin-restart` or `{ repo, localPath?, label? }`.
+ *
+ * @param {unknown} entry - one element of `repos`.
+ * @returns {{repo: string, localPath: string, label: string, bilibili: object|null}|null} null when unusable.
+ */
+export function normalizeEntry(entry) {
+  if (typeof entry === 'string') {
+    const repo = entry.trim()
+    return SLUG.test(repo) || SLUG_WITH_OWNER.test(repo) ? { repo, localPath: '', label: '', bilibili: null } : null
+  }
+  if (entry === null || typeof entry !== 'object') return null
+  const repo = text(entry.repo ?? entry.name)
+  if (!SLUG.test(repo) && !SLUG_WITH_OWNER.test(repo)) return null
+  const localPath = text(entry.localPath ?? entry.path)
+  return {
+    repo,
+    // Absolute only: a relative path would be resolved against the Host's own
+    // working directory, which is not the user's shell directory.
+    localPath: localPath !== '' && isAbsolute(localPath) ? localPath : '',
+    label: text(entry.label),
+    bilibili: normalizeBinding(entry.bilibili),
+  }
+}
+
+/**
+ * Parse the file tolerantly and report what had to be dropped.
+ *
+ * @param {string} raw - file contents.
+ * @returns {{ok: true, owner: string, repos: object[], dropped: number}|{ok: false, message: string}}
+ */
+export function parseConfig(raw) {
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    return { ok: false, message: `not valid JSON: ${error.message}` }
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { ok: false, message: 'expected a JSON object with "owner" and "repos"' }
+  }
+  if (parsed.repos !== undefined && !Array.isArray(parsed.repos)) {
+    return { ok: false, message: '"repos" must be an array' }
+  }
+  const declared = Array.isArray(parsed.repos) ? parsed.repos : []
+  const repos = []
+  const seen = new Set()
+  for (const entry of declared.slice(0, MAX_REPOS)) {
+    const normalized = normalizeEntry(entry)
+    if (normalized === null || seen.has(normalized.repo)) continue
+    seen.add(normalized.repo)
+    repos.push(normalized)
+  }
+  return { ok: true, owner: text(parsed.owner), repos, dropped: declared.length - repos.length }
+}
+
+/**
+ * Read the file; a missing file is an empty configuration, not an error.
+ * @param {string} file - absolute path.
+ * @returns {{exists: boolean, owner: string, repos: object[], dropped: number, problem: string|null}}
+ */
+export function readConfig(file) {
+  if (!existsSync(file)) return { exists: false, owner: '', repos: [], dropped: 0, problem: null }
+  const parsed = parseConfig(readFileSync(file, 'utf8'))
+  if (!parsed.ok) return { exists: true, owner: '', repos: [], dropped: 0, problem: `${file}: ${parsed.message}` }
+  return { exists: true, owner: parsed.owner, repos: parsed.repos, dropped: parsed.dropped, problem: null }
+}
+
+/**
+ * Write the file atomically.
+ *
+ * The plugin re-reads this file on every request, so a partially written file
+ * would be observed as a broken configuration and would blank the panel. The new
+ * content therefore lands via rename, and the previous revision is kept beside it.
+ *
+ * @param {string} file - absolute path.
+ * @param {{owner: string, repos: object[]}} config - what to store.
+ * @returns {string} the exact bytes written.
+ */
+export function writeConfig(file, config) {
+  const body = `${JSON.stringify({ owner: text(config.owner), repos: config.repos }, null, 2)}\n`
+  mkdirSync(dirname(file), { recursive: true })
+  if (existsSync(file)) {
+    try {
+      writeFileSync(`${file}.bak`, readFileSync(file))
+    } catch {
+      /* a missing backup must not block the write */
+    }
+  }
+  const temporary = `${file}.tmp`
+  writeFileSync(temporary, body, 'utf8')
+  renameSync(temporary, file)
+  return body
+}
+
+/**
+ * Whether a name may be registered at all.
+ * @param {unknown} repo - candidate.
+ * @returns {boolean}
+ */
+export function isValidRepoName(repo) {
+  return typeof repo === 'string' && (SLUG.test(repo) || SLUG_WITH_OWNER.test(repo))
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "dsh-plugin-cicd",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.0",
+  "description": "发布台（Release Console）for DeepSeek Harness: a sidebar entry and a full main-panel page that show what each repository has built, what it has released, whether the local checkout is ahead of the release, whether the copy installed in this profile is the published artifact, and which version npm holds — with buttons to trigger a build, cut a release, publish a draft, push that version to npm, install the release into the profile, and hand a restart to dsh-plugin-restart. It also carries the third channel: when a repository's release goes public, one short update note is posted under the video that introduces the plugin, with the credential obtained from a Bilibili sign-in inside the panel. Reuses the machine's authenticated gh CLI and the Host's own package manager, so the plugin stores no GitHub or npm credential of its own; the one credential it does own is the Bilibili session it created, kept in its own directory and never echoed back.",
+  "type": "module",
+  "icon": "./icon.svg",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "lib",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md",
+    "RELEASING.md",
+    "scripts",
+    "tests",
+    "LICENSE"
+  ],
+  "meta": {
+    "title": "DSH 插件发布台",
+    "description": "面向 DSH 插件仓库的持续构建与发布（CI/CD）：侧边栏图标 + 独立主面板，显示每个仓库的最近一次运行、已发布的 Release、本地是否领先于发布、本 profile 装的到底是哪一份（link: 本地检出 / Release 的 tgz），以及 npm 上是哪一版。浏览器登录、勾选仓库即可，复用本机已登录的 gh 与 Host 自己的包管理器，不另存 GitHub / npm 凭据。一个包两条渠道：发布、装 Release、升版本并发布为一个循环（装完面板接着问要不要重启，转发给 dsh-plugin-restart），推送 npm 是独立按钮（未登录时可在面板里粘贴 token 写入 npm 自己的 .npmrc，支持 2FA 一次性密码）。第三条渠道是 B 站更新播报：Release 公开后，在绑定的视频评论区自动补一条简短的更新说明——只认已公开的 Release（草稿不算），按 (仓库, tag) 幂等，绑定视频时写入基线所以不追发历史版本；凭据走面板内的 B 站登录（passport 网页二维码）或粘贴一次，落在插件自己的目录里、不回显，并且会真的去问一次账号接口——因为 biliup 默认写下的 cookies.json 是 BiliTV 登录，发评论走的却是 Web 接口。门禁与产包形状按 DSH bundle 设计（契约检查 + 整树 zip + 可安装 tgz + npm），任何带 ci.yml / release.yml 的仓库都能接。"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "github-actions",
+    "release",
+    "ci",
+    "cd",
+    "gh-cli"
+  ],
+  "license": "MIT",
+  "author": "林冠宇 (SOH4C4759) <107021339+SOH4C4759@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SOH4C4759/dsh-plugin-cicd.git"
+  },
+  "homepage": "https://github.com/SOH4C4759/dsh-plugin-cicd#readme",
+  "bugs": {
+    "url": "https://github.com/SOH4C4759/dsh-plugin-cicd/issues"
+  }
 }

package/scripts/configure.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * Configure the Release Console without editing YAML by hand.
+ *
+ * The plugin's row lives in the profile patch, which is the wrong place to keep a
+ * list that changes: hand-editing it is slow, easy to get wrong, and needs a
+ * restart to take effect. So the repository list lives in a JSON file this script
+ * owns, the row only has to be pointed at it once, and the plugin re-reads the
+ * file on every request — `add` is visible on the panel's next poll.
+ *
+ *   node scripts/configure.mjs list
+ *   node scripts/configure.mjs add dsh-plugin-restart --path F:\CodeProj\dsh-plugin-restart
+ *   node scripts/configure.mjs add other/repo
+ *   node scripts/configure.mjs remove dsh-plugin-restart
+ *   node scripts/configure.mjs owner SOH4C4759
+ *   node scripts/configure.mjs check            # what the panel would show right now
+ *
+ * Options:
+ *   --file <path>     manage a different file (default: $DSH_HOME/dsh-plugin-cicd/repos.json)
+ *   --json            machine-readable output
+ *   --url <base>      Host base URL for `check` (default: $DSH_WEB_URL or http://127.0.0.1:19387)
+ *
+ * Windows paths are written with backslashes and read back the same way; nothing
+ * here rewrites a path, so what you typed is what the plugin sees.
+ */
+
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join, resolve } from 'node:path'
+import { SLUG, SLUG_WITH_OWNER, isValidRepoName, readConfig, writeConfig } from '../lib/config-store.mjs'
+
+const DEFAULT_HOST_URL = 'http://127.0.0.1:19387'
+
+const argv = process.argv.slice(2)
+const options = { json: false, file: '', url: '', path: '', label: '' }
+const positional = []
+for (let index = 0; index < argv.length; index += 1) {
+  const token = argv[index]
+  if (token === '--json') options.json = true
+  else if (token === '--file') options.file = argv[++index] ?? ''
+  else if (token === '--url') options.url = argv[++index] ?? ''
+  else if (token === '--path') options.path = argv[++index] ?? ''
+  else if (token === '--label') options.label = argv[++index] ?? ''
+  else if (token.startsWith('--')) fail(`unknown option: ${token}`)
+  else positional.push(token)
+}
+
+const command = positional[0] ?? 'list'
+
+/** Print a message to stderr and exit non-zero. */
+function fail(message) {
+  process.stderr.write(`configure: ${message}\n`)
+  process.exit(2)
+}
+
+/** The managed file, resolved the same way the Host resolves it. */
+function configPath() {
+  if (options.file !== '') return resolve(options.file)
+  if (typeof process.env.DSH_CICD_CONFIG === 'string' && process.env.DSH_CICD_CONFIG !== '') return resolve(process.env.DSH_CICD_CONFIG)
+  const home = typeof process.env.DSH_HOME === 'string' && process.env.DSH_HOME !== ''
+    ? process.env.DSH_HOME
+    : join(process.env.USERPROFILE ?? homedir(), '.dsh')
+  return join(home, 'dsh-plugin-cicd', 'repos.json')
+}
+
+/** Read the managed file and turn a problem into a CLI error. */
+function loadConfig(file) {
+  const stored = readConfig(file)
+  if (stored.problem !== null) fail(`${stored.problem}. Fix or delete the file, then retry.`)
+  return { owner: stored.owner, repos: stored.repos, dropped: stored.dropped }
+}
+
+/** Validate one repository argument the way the Host will. */
+function checkRepoSlug(repo) {
+  if (repo === undefined) fail('a repository name is required')
+  if (!isValidRepoName(repo)) {
+    fail(`unusable repository name: ${JSON.stringify(repo)} — expected "name" or "owner/name"`)
+  }
+  return repo
+}
+
+/** Validate a local path: the Host ignores a relative one, so refuse it here. */
+function checkLocalPath(value) {
+  if (value === '') return ''
+  if (!isAbsolute(value)) fail(`--path must be absolute, got ${JSON.stringify(value)} (a relative path resolves against the Host's own directory)`)
+  return value
+}
+
+function emit(payload, human) {
+  if (options.json) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`)
+  else process.stdout.write(`${human}\n`)
+}
+
+const file = configPath()
+const config = loadConfig(file)
+
+switch (command) {
+  case 'list': {
+    const lines = [`config file: ${file}`, `owner:       ${config.owner === '' ? '(unset)' : config.owner}`, `repositories (${config.repos.length}):`]
+    for (const entry of config.repos) {
+      const bound = entry.bilibili?.bvid ? `  B站 ${entry.bilibili.bvid}${entry.bilibili.auto === false ? '（仅手动）' : ''}` : ''
+      lines.push(`  - ${entry.repo}${entry.localPath === undefined ? '' : `  →  ${entry.localPath}`}${entry.label === undefined ? '' : `  [${entry.label}]`}${bound}`)
+    }
+    if (config.repos.length === 0) lines.push('  (none — add one with: configure.mjs add <repo> --path <dir>)')
+    lines.push('', 'The panel re-reads this file on every poll, so changes apply without a restart.')
+    emit({ file, owner: config.owner, repos: config.repos }, lines.join('\n'))
+    break
+  }
+
+  case 'init': {
+    if (existsSync(file)) emit({ file, created: false }, `already exists: ${file}`)
+    else {
+      writeConfig(file, config)
+      emit({ file, created: true }, `created ${file}`)
+    }
+    break
+  }
+
+  case 'owner': {
+    const owner = positional[1]
+    if (owner === undefined || owner === '') fail('owner requires a GitHub login')
+    if (!SLUG.test(owner)) fail(`unusable GitHub login: ${JSON.stringify(owner)}`)
+    config.owner = owner
+    writeConfig(file, config)
+    emit({ file, owner }, `owner set to ${owner} in ${file}`)
+    break
+  }
+
+  case 'add': {
+    const repo = checkRepoSlug(positional[1])
+    const localPath = checkLocalPath(options.path)
+    const existing = config.repos.findIndex((entry) => entry.repo === repo)
+    /* The Bilibili binding is not something this command knows about, so an
+       `add` that overwrote it would silently unbind a video — the failure being
+       invisible until a release note never appears. It is carried over. */
+    const binding = existing === -1 ? null : config.repos[existing].bilibili ?? null
+    const entry = {
+      repo,
+      ...(localPath !== '' ? { localPath } : {}),
+      ...(options.label !== '' ? { label: options.label } : {}),
+      ...(binding === null ? {} : { bilibili: binding }),
+    }
+    if (existing === -1) config.repos.push(entry)
+    else config.repos[existing] = entry
+    writeConfig(file, config)
+    const notes = [`${existing === -1 ? 'added' : 'updated'} ${repo} in ${file}`]
+    if (localPath !== '' && !existsSync(localPath)) notes.push(`note: ${localPath} does not exist yet — the panel will show "not a git checkout" until it does`)
+    if (localPath === '') notes.push('note: no --path given, so the panel cannot compare the local checkout against the release')
+    if (!SLUG_WITH_OWNER.test(repo) && config.owner === '') notes.push(`note: "${repo}" has no owner and the file records none — set one with: configure.mjs owner <login>`)
+    notes.push('It applies on the panel\'s next poll; no restart needed.')
+    emit({ file, entry, configSource: 'file' }, notes.join('\n'))
+    break
+  }
+
+  case 'remove': {
+    const repo = checkRepoSlug(positional[1])
+    const before = config.repos.length
+    config.repos = config.repos.filter((entry) => entry.repo !== repo)
+    if (config.repos.length === before) fail(`${repo} is not registered in ${file}`)
+    writeConfig(file, config)
+    emit({ file, removed: repo }, `removed ${repo} from ${file}`)
+    break
+  }
+
+  case 'check': {
+    const base = options.url !== '' ? options.url : (process.env.DSH_WEB_URL ?? DEFAULT_HOST_URL)
+    /** POST one route; the Host gates these to loopback, which this is. */
+    const post = async (path, body) => {
+      const response = await fetch(`${base}${path}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body ?? {}),
+      })
+      return response.json()
+    }
+    let status
+    try {
+      status = await post('/api/dsh-cicd/status', {})
+    } catch (error) {
+      fail(`cannot reach the Host at ${base} (${error.message}). Is DSH running? Pass --url <base> if it listens elsewhere.`)
+    }
+    if (status?.ok !== true) fail(`the Host refused /status: ${status?.message ?? 'unknown error'}`)
+    const overview = await post('/api/dsh-cicd/overview', { force: true })
+
+    const value = status.value
+    // Read defensively: a Host running an older copy of this plugin answers with
+    // fewer fields, and a diagnosis tool that crashes on that is useless exactly
+    // when it is needed.
+    const gh = value.gh ?? {}
+    const scopes = Array.isArray(gh.scopes) ? gh.scopes : []
+    const missingScopes = Array.isArray(gh.missingScopes) ? gh.missingScopes : []
+    const lines = [
+      `Host:        ${base}`,
+      `gh:          ${gh.available ? (gh.version ?? 'present') : 'NOT FOUND'}${gh.authenticated ? ` — ${gh.account ?? 'signed in'}` : ' — not signed in'}`,
+      `scopes:      ${scopes.length === 0 ? '(not reported by this Host)' : scopes.join(', ')}${missingScopes.length > 0 ? `  MISSING: ${missingScopes.join(', ')}` : ''}`,
+      `config from: ${value.configSource ?? '(older Host)'}  (${value.configFile ?? 'unknown'})`,
+    ]
+    if (value.configProblem) lines.push(`config problem: ${value.configProblem}`)
+    lines.push(`repositories: ${Array.isArray(value.repos) ? value.repos.length : 0}`)
+    for (const repo of overview?.value?.repos ?? []) {
+      const run = repo.latestRun === null ? 'no runs' : `${repo.latestRun.workflow}/${repo.latestRun.conclusion || repo.latestRun.status}`
+      const releases = repo.releases.length === 0 ? 'no releases' : repo.releases.map((entry) => `${entry.tag}${entry.draft ? '(draft)' : ''}`).join(',')
+      const local = repo.local?.available ? `dirty=${repo.local.dirty} ahead=${repo.local.ahead} behind=${repo.local.behind}` : `local: ${repo.local?.reason ?? 'unknown'}`
+      const problems = repo.problems.length > 0 ? `  PROBLEMS: ${repo.problems.join(' | ')}` : ''
+      lines.push(`  - ${repo.label.padEnd(28)} v${repo.version ?? '?'}  ${repo.published ? 'published' : 'unpublished'}  ${run}  ${releases}  ${local}${problems}`)
+    }
+    emit({ status: value, overview: overview?.value ?? null }, lines.join('\n'))
+    break
+  }
+
+  default:
+    fail(`unknown command: ${command}. Try list | init | add | remove | owner | check`)
+}

package/scripts/push-via-api.ps1

@@ -0,0 +1,111 @@
+# Push local commits to GitHub through the Git Data API.
+#
+# Why this exists: on this machine `github.com:443` is intermittently blocked
+# while `api.github.com:443` stays reachable, so `git push` fails with
+# "Connection was reset" / "Could not connect to server". The API can create the
+# same objects, and because git objects are content-addressed the reconstructed
+# commit carries the *same SHA* as the local one — so updating the ref leaves the
+# clone and the remote identical, with no divergence to reconcile later.
+#
+# Safety: every reconstructed commit SHA is compared against the local commit
+# SHA before the ref is touched. A single mismatch aborts without moving the ref.
+param(
+  [Parameter(Mandatory = $true)][string]$RepoPath,
+  [string]$Owner = 'SOH4C4759',
+  [string]$Repo
+)
+
+$ErrorActionPreference = 'Stop'
+if (-not $Repo) { $Repo = Split-Path $RepoPath -Leaf }
+
+function Write-JsonFile([string]$Path, $Value) {
+  [IO.File]::WriteAllText($Path, ($Value | ConvertTo-Json -Depth 8 -Compress), (New-Object Text.UTF8Encoding($false)))
+}
+
+function Get-BlobBytes([string]$BlobSha, [string]$Scratch) {
+  # cmd redirection is byte-exact; PowerShell's native-output capture is not.
+  $out = Join-Path $Scratch 'blob.bin'
+  cmd /c "git cat-file blob $BlobSha > `"$out`""
+  if ($LASTEXITCODE -ne 0) { throw "git cat-file blob $BlobSha failed" }
+  return [IO.File]::ReadAllBytes($out)
+}
+
+Push-Location $RepoPath
+try {
+  $head = (git rev-parse HEAD).Trim()
+  $remote = (gh api "repos/$Owner/$Repo/git/ref/heads/main" --jq '.object.sha').Trim()
+  Write-Host "[$Repo] remote main $($remote.Substring(0,7))  local HEAD $($head.Substring(0,7))"
+  if ($remote -eq $head) { Write-Host "[$Repo] already in sync"; return }
+
+  $chain = @()
+  $cursor = $head
+  while ($cursor -ne $remote) {
+    $chain = @($cursor) + $chain
+    $cursor = (git rev-parse "$cursor^").Trim()
+    if ($chain.Count -gt 20) { throw "[$Repo] remote main is not an ancestor of HEAD — refusing to rewrite history" }
+  }
+  Write-Host "[$Repo] $($chain.Count) commit(s) to publish"
+
+  $scratch = Join-Path $env:TEMP ("apipush-" + [guid]::NewGuid().ToString('N'))
+  New-Item -ItemType Directory -Path $scratch | Out-Null
+  $parent = $remote
+
+  foreach ($commit in $chain) {
+    $meta = (git log -1 --format='%H%n%T%n%an%n%ae%n%aI%n%cn%n%ce%n%cI' $commit) -split "`n"
+    $expectedTree = $meta[1].Trim()
+    $an = $meta[2]; $ae = $meta[3]; $ad = $meta[4].Trim()
+    $cn = $meta[5]; $ce = $meta[6]; $cd = $meta[7].Trim()
+    $message = ((git log -1 --format='%B' $commit) -join "`n")
+
+    $entries = @()
+    foreach ($line in (git show --name-status --format= $commit)) {
+      if ($line -match '^\s*$') { continue }
+      $parts = $line -split "`t"
+      $status = $parts[0]; $path = $parts[1]
+      if ($status -notmatch '^(A|M)$') { throw "[$Repo] unsupported change '$status' for $path — refusing" }
+      $blobSha = (git rev-parse "${commit}:$path").Trim()
+      $bytes = Get-BlobBytes $blobSha $scratch
+      $blobBody = Join-Path $scratch 'blob.json'
+      Write-JsonFile $blobBody @{ content = [Convert]::ToBase64String($bytes); encoding = 'base64' }
+      $uploaded = (gh api --method POST "repos/$Owner/$Repo/git/blobs" --input $blobBody --jq '.sha').Trim()
+      if ($uploaded -ne $blobSha) { throw "[$Repo] blob round-trip changed $path ($blobSha -> $uploaded)" }
+      $entries += @{ path = $path; mode = '100644'; type = 'blob'; sha = $blobSha }
+    }
+
+    $parentTree = (gh api "repos/$Owner/$Repo/git/commits/$parent" --jq '.tree.sha').Trim()
+    $treeBody = Join-Path $scratch 'tree.json'
+    Write-JsonFile $treeBody @{ base_tree = $parentTree; tree = @($entries) }
+    $newTree = (gh api --method POST "repos/$Owner/$Repo/git/trees" --input $treeBody --jq '.sha').Trim()
+    if ($newTree -ne $expectedTree) { throw "[$Repo] tree mismatch for $($commit.Substring(0,7)): $newTree != $expectedTree" }
+
+    $commitBody = Join-Path $scratch 'commit.json'
+    Write-JsonFile $commitBody @{
+      message   = $message
+      tree      = $newTree
+      parents   = @($parent)
+      author    = @{ name = $an; email = $ae; date = $ad }
+      committer = @{ name = $cn; email = $ce; date = $cd }
+    }
+    $created = (gh api --method POST "repos/$Owner/$Repo/git/commits" --input $commitBody --jq '.sha').Trim()
+    if ($created -ne $commit) { throw "[$Repo] commit mismatch: $created != $commit — no ref was moved" }
+    Write-Host "  + $($commit.Substring(0,7)) $((git log -1 --format='%s' $commit))  [sha identical]"
+    $parent = $commit
+  }
+
+  $refBody = Join-Path $scratch 'ref.json'
+  Write-JsonFile $refBody @{ sha = $parent; force = $false }
+  gh api --method PATCH "repos/$Owner/$Repo/git/refs/heads/main" --input $refBody --jq '.object.sha' | Out-Null
+
+  $after = (gh api "repos/$Owner/$Repo/git/ref/heads/main" --jq '.object.sha').Trim()
+  if ($after -ne $head) { throw "[$Repo] ref update did not land where expected: $after" }
+
+  # A real `git push` also moves the remote-tracking ref; going through the API does
+  # not, and a stale origin/main makes `git status` report a phantom "ahead" — which
+  # is exactly what a release panel reading `@{u}...HEAD` would then show.
+  & git update-ref "refs/remotes/origin/main" $after
+  Write-Host "[$Repo] PUSHED — remote main now $($after.Substring(0,7)), identical to local HEAD (tracking ref updated)"
+
+  Remove-Item -Recurse -Force $scratch
+} finally {
+  Pop-Location
+}