AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.
HTML ai-agentcloudflarecloudflare-d1cloudflare-r2cloudflare-workersdockerelectronevernoteevernote-alternativeknowledge-basemcpnote-takingobsidian-alternativeoffline-firstpersonal-knowledge-basepwaself-hostedsqlitetiptapweb-clipper
fix(deploy): preserve fork workflows during updates
tianma-if06297ff11f17
diff --git a/.github/workflows/sync-edgeever-upstream.yml b/.github/workflows/sync-edgeever-upstream.ymlindex de6375e8..24c462bf 100644--- a/.github/workflows/sync-edgeever-upstream.yml+++ b/.github/workflows/sync-edgeever-upstream.yml@@ -1,8 +1,8 @@name: Update deployed EdgeEver# Keeps a deployment Fork aligned with upstream EdgeEver.-# Deployment Forks are read-only mirrors by default: when content differs,-# main resets to the selected Release (or edge main) and triggers Cloudflare.+# Deployment Forks mirror product code by default while preserving their local+# workflow directory so GITHUB_TOKEN never needs permission to rewrite Actions.# The rare customized Fork must explicitly opt in to merge preservation.on:@@ -95,8 +95,10 @@ jobs:head_version="unknown"fi- # Updater-only differences do not trigger a product update.- content_diff="$(git diff --name-only "${target_commit}" HEAD -- ':!.github/workflows/sync-edgeever-upstream.yml' ':!scripts/upstream-sync-plan.mjs' || true)"+ # GitHub blocks GITHUB_TOKEN pushes that add, modify, or remove Actions+ # workflows. Deployment forks therefore compare and update only the+ # managed product tree; their complete workflow directory stays local.+ content_diff="$(git diff --name-only "${target_commit}" HEAD -- . ':(exclude).github/workflows/**' || true)"content_matches_target=falseif [ -z "${content_diff}" ]; thencontent_matches_target=true@@ -161,13 +163,13 @@ jobs:echo "**Application content already matches upstream target** (history tip may differ). No git update is needed for deployment.";;behind_target)- echo "**Fork is behind upstream.** Aligning with a hard reset to the target commit (deploy-mirror path)."+ echo "**Fork is behind upstream.** Applying the target product snapshot while preserving downstream workflows.";;deploy_mirror_reset)- echo "**Deployment mirror differs from upstream.** Resetting onto the selected target; no Fork code is preserved in the default mode."+ echo "**Deployment mirror differs from upstream.** Replacing managed product files with the selected target while preserving downstream workflows.";;deploy_mirror_ahead)- echo "**Deploy-only fork is ahead of the selected upstream target.** Resetting onto that target."+ echo "**Deploy-only fork is ahead of the selected upstream target.** Applying that target's product snapshot while preserving downstream workflows.";;customized_contains_target)echo "**Opt-in customized fork already contains the upstream target.** Preserving its application changes without another merge."@@ -184,7 +186,7 @@ jobs:echo "\`force_redeploy\` is set: will push an empty commit so Cloudflare Workers Builds runs again."fiecho ""- echo "Prefer this workflow over GitHub **Sync fork**. The default mirror mode intentionally owns \`main\` and resets it to the selected upstream target."+ echo "Prefer this workflow over GitHub **Sync fork**. Mirror mode owns the managed product tree while preserving the Fork's local \`.github/workflows/**\`."} >> "${GITHUB_STEP_SUMMARY}"echo "channel=${UPDATE_CHANNEL} target=${target_ref}@${target_commit:0:12} (v${target_version}) head=${head_commit:0:12} (v${head_version}) reason=${reason} align=${align_mode} update=${update_required} republish=${republish_only}"@@ -201,26 +203,18 @@ jobs:git config user.name "edgeever-updater[bot]"git config user.email "edgeever-updater[bot]@users.noreply.github.com"- case "${ALIGN_MODE}" in- reset)- git reset --hard "${TARGET_COMMIT}"- git clean -fd- echo "Reset main onto ${TARGET_REF} (${TARGET_COMMIT:0:12}) because ${REASON}."- ;;- merge)- if ! git merge --no-edit -m "chore: update EdgeEver from ${TARGET_REF}" "${TARGET_COMMIT}"; then- git merge --abort || true- echo "Merge from ${TARGET_REF} conflicted with local application changes." >&2- echo "Resolve the customized fork manually, or remove EDGE_EVER_PRESERVE_FORK_CHANGES to return to mirror mode." >&2- exit 1- fi- echo "Merged ${TARGET_REF} (${TARGET_COMMIT:0:12}) because ${REASON}."- ;;- *)- echo "Unsupported align mode: ${ALIGN_MODE}" >&2- exit 1- ;;- esac+ helper_path="${RUNNER_TEMP}/prepare-upstream-sync.mjs"+ if git cat-file -e "${TARGET_COMMIT}:scripts/prepare-upstream-sync.mjs" 2>/dev/null; then+ git show "${TARGET_COMMIT}:scripts/prepare-upstream-sync.mjs" > "${helper_path}"+ else+ cp scripts/prepare-upstream-sync.mjs "${helper_path}"+ fi++ EDGE_SYNC_ALIGN_MODE="${ALIGN_MODE}" \+ EDGE_SYNC_BASE_COMMIT="HEAD" \+ EDGE_SYNC_TARGET_COMMIT="${TARGET_COMMIT}" \+ node "${helper_path}" prepare+ echo "Prepared ${ALIGN_MODE} update from ${TARGET_REF} (${TARGET_COMMIT:0:12}) because ${REASON}."- name: Set up Bunif: steps.upstream.outputs.align_mode == 'merge'@@ -243,6 +237,7 @@ jobs:if: steps.upstream.outputs.update_required == 'true' || steps.upstream.outputs.republish_only == 'true'env:TARGET_REF: ${{ steps.upstream.outputs.target_ref }}+ TARGET_COMMIT: ${{ steps.upstream.outputs.target_commit }}UPDATE_REQUIRED: ${{ steps.upstream.outputs.update_required }}REPUBLISH_ONLY: ${{ steps.upstream.outputs.republish_only }}ALIGN_MODE: ${{ steps.upstream.outputs.align_mode }}@@ -260,23 +255,25 @@ jobs:exit 0fi- if [ "${ALIGN_MODE}" = "reset" ]; then- if [ "${REASON}" = "behind_target" ]; then- git push origin HEAD:main- echo "mode=fast_forward" >> "${GITHUB_OUTPUT}"- echo "Published fast-forward main for ${TARGET_REF}."- else- # Diverged mirrors require a guarded history rewrite.- git push --force-with-lease origin HEAD:main- echo "mode=force_with_lease" >> "${GITHUB_OUTPUT}"- echo "Published reset main for ${TARGET_REF}."- fi- else- git push origin HEAD:main- echo "mode=push" >> "${GITHUB_OUTPUT}"- echo "Published merge for ${TARGET_REF}."+ git commit \+ -m "chore: update EdgeEver from ${TARGET_REF}" \+ -m "EdgeEver-Upstream-Commit: ${TARGET_COMMIT}"++ if ! git diff --quiet HEAD^ HEAD -- .github/workflows; then+ echo "Refusing to publish an update that changes downstream GitHub Actions workflows." >&2+ exit 1fi+ if [ "${ALIGN_MODE}" = "snapshot" ] && \+ ! git diff --quiet "${TARGET_COMMIT}" HEAD -- . ':(exclude).github/workflows/**'; then+ echo "Prepared product tree does not match ${TARGET_REF}." >&2+ exit 1+ fi++ git push origin HEAD:main+ echo "mode=${ALIGN_MODE}_commit" >> "${GITHUB_OUTPUT}"+ echo "Published ${ALIGN_MODE} update for ${TARGET_REF} without changing downstream workflows."+- name: Trigger Cloudflare Deploy Hookif: steps.publish.outcome == 'success'env:diff --git a/docs/agent-deploy-cloudflare.md b/docs/agent-deploy-cloudflare.mdindex 9da8980a..6285d1e8 100644--- a/docs/agent-deploy-cloudflare.md+++ b/docs/agent-deploy-cloudflare.md@@ -13,7 +13,8 @@ This document defines the standard operating specifications and conventions for2. **Enable Workflow**- In the **Actions** tab of the Forked repository, enable the **Update deployed EdgeEver** automatic update workflow (required on public forks: scheduled workflows are disabled by default).- - An ordinary Fork is a deployment mirror by default. No update variable is required: the workflow owns `main` and may reset it to the selected upstream Release before triggering Cloudflare.+ - An ordinary Fork is a deployment mirror by default. No update variable is required: the workflow applies the selected upstream Release's product snapshot to `main` before triggering Cloudflare.+ - The updater preserves the Fork's complete `.github/workflows/**` directory. Official packaging, signing, testing, and Release workflows remain guarded to `tianma-if/edgeever` and are never rewritten by the downstream updater.- Only a Fork that intentionally maintains application-code changes should create the Actions repository variable `EDGE_EVER_PRESERVE_FORK_CHANGES=true`. This opts into merges and requires the owner to resolve future conflicts; it is not needed for normal deployments.3. **Cloudflare Project Import**@@ -48,4 +49,4 @@ This document defines the standard operating specifications and conventions for- Manually trigger **Update deployed EdgeEver** once in the Fork's **Actions** tab.- Open the job **Summary** and confirm it reports Fork mode `mirror`, the upstream target (stable Release or edge `main`), and either an update publish or an explicit *already aligned* result.- Confirm Cloudflare **Deployments** builds the published `main` commit when a push occurred.- - Do not edit deployment files or rely on GitHub **Sync fork** for routine upgrades; the workflow is the only synchronization path needed by a normal deployment Fork.+ - Do not edit deployment files or rely on GitHub **Sync fork** for routine upgrades; the workflow is the only synchronization path needed by a normal deployment Fork. Use **Sync fork** once only when an old Fork must receive a newer updater workflow itself, then return to **Update deployed EdgeEver**.diff --git a/docs/agent-deploy-cloudflare.zh-CN.md b/docs/agent-deploy-cloudflare.zh-CN.mdindex 6a214ffc..c6b3054a 100644--- a/docs/agent-deploy-cloudflare.zh-CN.md+++ b/docs/agent-deploy-cloudflare.zh-CN.md@@ -13,7 +13,8 @@2. **启用工作流**- 在 Fork 仓库的 **Actions** 标签页中,启用 **Update deployed EdgeEver** 自动更新工作流(公共 Fork 上定时任务默认关闭,必须手动启用)。- - 普通 Fork 默认作为部署镜像,无需配置任何更新变量:工作流负责管理 `main`,可将其重置到选定的上游 Release,再触发 Cloudflare。+ - 普通 Fork 默认作为部署镜像,无需配置任何更新变量:工作流会把所选上游 Release 的产品代码快照应用到 `main`,再触发 Cloudflare。+ - 更新器会完整保留 Fork 自己的 `.github/workflows/**` 目录。官方打包、签名、测试与 Release 工作流继续通过 `tianma-if/edgeever` 仓库门禁限制执行,也不会被下游更新器改写。- 只有明确维护了应用代码修改的 Fork,才应创建 Actions 仓库变量 `EDGE_EVER_PRESERVE_FORK_CHANGES=true`。启用后改为 merge,并由仓库所有者处理未来冲突;普通部署无需设置。3. **Cloudflare 项目导入**@@ -48,4 +49,4 @@- 在 Fork 的 **Actions** 中手动运行一次 **Update deployed EdgeEver**。- 打开 Job **Summary**,确认 Fork mode 为 `mirror`,并显示上游目标(stable Release 或 edge `main`),以及「已发布更新」或明确的「已对齐」结果。- 若发生了 push,确认 Cloudflare **Deployments** 构建的是对应的 `main` commit。- - 普通部署 Fork 不应修改部署文件,日常升级也不要依赖 GitHub **Sync fork**;本工作流就是唯一需要的同步路径。+ - 普通部署 Fork 不应修改部署文件,日常升级也不要依赖 GitHub **Sync fork**;本工作流就是唯一需要的同步路径。只有旧 Fork 必须取得新版更新工作流本身时,才使用一次 **Sync fork**,之后继续使用 **Update deployed EdgeEver**。diff --git a/docs/cloudflare-workers-builds.md b/docs/cloudflare-workers-builds.mdindex 6c62c6ea..af961346 100644--- a/docs/cloudflare-workers-builds.md+++ b/docs/cloudflare-workers-builds.md@@ -18,10 +18,12 @@ Configure `EDGE_EVER_AUTH_PASSWORD` under the Worker's **Settings -> Variables a- **Update deployed EdgeEver** keeps a deployment Fork as an upstream **deploy mirror**:- Default channel `stable` tracks the latest formal Release tag.- Set the GitHub Repository Variable `EDGE_EVER_UPDATE_CHANNEL=edge` to follow upstream `main`.- - Read-only forks (no app code changes) **reset** onto the target when behind; customized forks **merge** and fail closed on conflicts.+ - Read-only forks (no app code changes) apply the target's product snapshot in a new linear commit; customized forks merge product changes and fail closed on conflicts.+ - The complete downstream `.github/workflows/**` directory is preserved. Official packaging, signing, testing, and Release workflows are not part of automatic product updates, so `GITHUB_TOKEN` never needs permission to rewrite Actions workflows.- Every run writes a job **Summary** with channel, target version, decision reason, and whether a push happened. A green run that says *Already on upstream target* is success, not a silent failure.- Prefer this workflow over GitHub **Sync fork**. Sync fork follows upstream `main` history and can make the next stable run a deliberate no-op.- Optional: repository secret `EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL` triggers a Cloudflare Deploy Hook after a successful push (useful when the Git integration misses a push).- Optional: re-run the workflow with **force_redeploy** to push an empty commit when Git is already current but Cloudflare needs another build.- Build failure: inspect the Worker **Deployments** log and confirm the Deployment commit SHA matches Fork `main`.- Scheduled update never runs: on a public Fork, enable **Update deployed EdgeEver** under **Actions** (scheduled workflows are disabled by default on forks, and may pause after long inactivity).+- Update push is rejected with `without workflows permission`: the Fork still has an older updater. Use GitHub **Sync fork** once with the repository owner's permission, then re-run **Update deployed EdgeEver**. Routine product updates do not require **Sync fork** after that bootstrap.diff --git a/docs/cloudflare-workers-builds.zh-CN.md b/docs/cloudflare-workers-builds.zh-CN.mdindex 20d36859..ee52319d 100644--- a/docs/cloudflare-workers-builds.zh-CN.md+++ b/docs/cloudflare-workers-builds.zh-CN.md@@ -18,10 +18,12 @@- **Update deployed EdgeEver** 把部署用 Fork 当作上游的 **部署镜像** 来维护:- 默认 `stable` 通道跟随最新正式 Release tag。- 设置 GitHub Repository Variable `EDGE_EVER_UPDATE_CHANNEL=edge` 后跟随上游 `main`。- - 只读 Fork(未改应用代码)在落后时会 **reset** 到目标版本;有本地业务改动的 Fork 走 **merge**,冲突则失败并保持线上不变。+ - 只读 Fork(未改应用代码)会用一个新的线性提交应用目标版本的产品代码快照;有本地业务改动的 Fork 合并产品代码,冲突则失败并保持线上不变。+ - 下游完整的 `.github/workflows/**` 目录会原样保留。官方打包、签名、测试与 Release 工作流不参与产品代码自动更新,因此 `GITHUB_TOKEN` 无需取得改写 Actions 工作流的权限。- 每次运行都会写 Job **Summary**:通道、目标版本、判定原因、是否 push。若 Summary 写明 *Already on upstream target* / 已对齐,绿色成功表示「已是目标版本」,不是静默故障。- 请优先用本工作流,而不是 GitHub **Sync fork**。Sync fork 跟的是上游 `main` 历史,可能让下一次 stable 运行合理变为 no-op。- 可选:仓库 Secret `EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL`,在成功 push 后触发 Cloudflare Deploy Hook(Git 集成偶发未构建时有用)。- 可选:Git 已是最新但 Cloudflare 需要再构建时,手动运行工作流并勾选 **force_redeploy**(会推送空 commit)。- 构建失败:查看 Worker **Deployments** 日志,确认部署 commit SHA 与 Fork `main` 一致。- 定时任务从不运行:公共 Fork 需在 **Actions** 中启用 **Update deployed EdgeEver**(Fork 上 schedule 默认禁用,长期不活跃也可能被暂停)。+- 更新 push 被 `without workflows permission` 拒绝:说明 Fork 仍在使用旧版更新器。请用仓库所有者权限执行一次 GitHub **Sync fork**,再重新运行 **Update deployed EdgeEver**;完成这次引导后,日常产品更新不再需要 **Sync fork**。diff --git a/docs/deploy-cloudflare-button.md b/docs/deploy-cloudflare-button.mdindex d9e274a7..afb77e1e 100644--- a/docs/deploy-cloudflare-button.md+++ b/docs/deploy-cloudflare-button.md@@ -107,5 +107,6 @@ You can also pick `stable` / `edge` when manually running the workflow.2. Run it once with **Run workflow**. Open the job **Summary**: it states the upstream target version and whether the fork was updated, already aligned, or failed.3. A green run with *Already on upstream target* means Git already matches that channel — not a broken skip. If the live site is still old, check Cloudflare **Deployments** commit SHA, or re-run with **force_redeploy**.4. Prefer this workflow over GitHub **Sync fork** for day-to-day upgrades.+ 5. If an old updater fails with `without workflows permission`, use **Sync fork** once as the repository owner, then re-run **Update deployed EdgeEver**. The current updater preserves `.github/workflows/**`, so later product updates do not hit this permission boundary.- **Push succeeded but site unchanged**: Confirm Workers Builds ran for the new `main` SHA. Optionally add repository secret `EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL` so the workflow can call a Deploy Hook after publish.- **Reset or Manual Recovery**: See the [Cloudflare Manual Deployment Guide](manual-deploy.md).diff --git a/docs/deploy-cloudflare-button.zh-CN.md b/docs/deploy-cloudflare-button.zh-CN.mdindex 6cc0be1e..33cd8ba9 100644--- a/docs/deploy-cloudflare-button.zh-CN.md+++ b/docs/deploy-cloudflare-button.zh-CN.md@@ -107,5 +107,6 @@ EDGE_EVER_UPDATE_CHANNEL=edge2. 手动 **Run workflow** 一次,打开 Job **Summary**:会写明上游目标版本,以及本次是「已更新」「已对齐」还是失败。3. 若绿色成功且 Summary 为 *Already on upstream target* / 已对齐,表示 Git 已是该通道目标版本,不是静默故障。若网站仍旧,请对照 Cloudflare **Deployments** 的 commit SHA,或勾选 **force_redeploy** 再跑一次。4. 日常升级请优先用本工作流,而不是 GitHub **Sync fork**。+ 5. 若旧版更新器报错 `without workflows permission`,请使用仓库所有者身份执行一次 **Sync fork**,然后重新运行 **Update deployed EdgeEver**。新版更新器会保留 `.github/workflows/**`,后续产品更新不会再触发这项权限限制。- **Git 已 push 但网站没变**:确认 Workers Builds 是否针对新的 `main` SHA 构建。可选:添加仓库 Secret `EDGE_EVER_CLOUDFLARE_DEPLOY_HOOK_URL`,让工作流在 publish 后调用 Deploy Hook。- **需要重置或手动恢复部署**:请参阅 [手动部署指南](manual-deploy.zh-CN.md)。diff --git a/scripts/prepare-upstream-sync.mjs b/scripts/prepare-upstream-sync.mjsnew file mode 100644index 00000000..059aebe6--- /dev/null+++ b/scripts/prepare-upstream-sync.mjs@@ -0,0 +1,254 @@+import { execFileSync } from "node:child_process";+import { resolve } from "node:path";+import { fileURLToPath } from "node:url";++const protectedWorkflowPath = ".github/workflows";++function runGit(arguments_, { allowFailure = false, cwd = process.cwd() } = {}) {+ try {+ const stdout = execFileSync("git", arguments_, {+ cwd,+ encoding: "utf8",+ stdio: ["ignore", "pipe", "pipe"],+ });+ return { status: 0, stderr: "", stdout };+ } catch (error) {+ const status = Number.isInteger(error.status) ? error.status : 1;+ const stderr = String(error.stderr || "");+ const stdout = String(error.stdout || "");+ if (allowFailure) return { status, stderr, stdout };++ const details = [stdout, stderr]+ .map((value) => value.trim())+ .filter(Boolean)+ .join("\n");+ throw new Error(`git ${arguments_.join(" ")} failed${details ? `:\n${details}` : ""}`);+ }+}++function resolveCommit(cwd, revision) {+ const result = runGit(["rev-parse", "--verify", `${revision}^{commit}`], { cwd });+ const commit = result.stdout.trim();+ if (!commit) {+ throw new Error(`git rev-parse returned no commit for ${revision} in ${cwd}`);+ }+ return commit;+}++function restoreProtectedWorkflows(cwd, baseCommit) {+ const workflowsExist = runGit(+ ["cat-file", "-e", `${baseCommit}:${protectedWorkflowPath}`],+ { allowFailure: true, cwd },+ );++ if (workflowsExist.status === 0) {+ runGit(+ [+ "restore",+ `--source=${baseCommit}`,+ "--staged",+ "--worktree",+ "--",+ protectedWorkflowPath,+ ],+ { cwd },+ );+ return;+ }++ runGit(["rm", "-r", "-f", "--ignore-unmatch", "--", protectedWorkflowPath], { cwd });+}++function requireNoWorkflowChanges(cwd, baseCommit) {+ const result = runGit(+ ["diff", "--cached", "--quiet", baseCommit, "--", protectedWorkflowPath],+ { allowFailure: true, cwd },+ );+ if (result.status === 1) {+ throw new Error(`${protectedWorkflowPath} must remain unchanged in deployment forks`);+ }+ if (result.status !== 0) {+ throw new Error(`Could not verify the protected workflow tree (git diff exited ${result.status})`);+ }+}++function requirePreparedChanges(cwd, baseCommit) {+ const result = runGit(["diff", "--cached", "--quiet", baseCommit], {+ allowFailure: true,+ cwd,+ });+ if (result.status === 0) {+ throw new Error("The upstream sync plan requested an update, but no managed files changed");+ }+ if (result.status !== 1) {+ throw new Error(`Could not verify the prepared update (git diff exited ${result.status})`);+ }+}++function prepareSnapshot(cwd, baseCommit, targetCommit) {+ runGit(["read-tree", "--reset", "-u", targetCommit], { cwd });+ restoreProtectedWorkflows(cwd, baseCommit);++ const managedTreeMatches = runGit(+ [+ "diff",+ "--cached",+ "--quiet",+ targetCommit,+ "--",+ ".",+ ":(exclude).github/workflows/**",+ ],+ { allowFailure: true, cwd },+ );+ if (managedTreeMatches.status !== 0) {+ throw new Error("Prepared deployment tree does not match the selected upstream target");+ }+}++function resolveCustomizedMergeBase(cwd, baseCommit, targetCommit) {+ const message = runGit(+ [+ "log",+ "-1",+ "--grep=^EdgeEver-Upstream-Commit: ",+ "--format=%B",+ baseCommit,+ ],+ { cwd },+ ).stdout;+ const recordedRevision = message.match(/^EdgeEver-Upstream-Commit:\s*(\S+)\s*$/m)?.[1];+ if (recordedRevision) {+ const recordedCommit = runGit(+ ["rev-parse", "--verify", `${recordedRevision}^{commit}`],+ { allowFailure: true, cwd },+ );+ if (recordedCommit.status === 0 && recordedCommit.stdout.trim()) {+ return recordedCommit.stdout.trim();+ }+ }++ return runGit(["merge-base", baseCommit, targetCommit], { cwd }).stdout.trim();+}++function prepareCustomizedMerge(cwd, baseCommit, targetCommit) {+ const mergeBase = resolveCustomizedMergeBase(cwd, baseCommit, targetCommit);+ if (!mergeBase) throw new Error("Could not resolve the customized fork's upstream base");++ const replaceRef = `refs/replace/${baseCommit}`;+ if (runGit(["show-ref", "--quiet", "--verify", replaceRef], {+ allowFailure: true,+ cwd,+ }).status === 0) {+ throw new Error(`Refusing to overwrite existing Git replacement ${replaceRef}`);+ }++ const baseTree = runGit(["rev-parse", `${baseCommit}^{tree}`], { cwd }).stdout.trim();+ const syntheticCommit = runGit(+ [+ "commit-tree",+ baseTree,+ "-p",+ mergeBase,+ "-m",+ "temporary EdgeEver customized sync base",+ ],+ { cwd },+ ).stdout.trim();+ runGit(["replace", baseCommit, syntheticCommit], { cwd });++ let mergedTree = "";+ try {+ const merge = runGit(["merge", "--no-commit", "--no-ff", targetCommit], {+ allowFailure: true,+ cwd,+ });+ const mergeInProgress = runGit(["rev-parse", "--quiet", "--verify", "MERGE_HEAD"], {+ allowFailure: true,+ cwd,+ }).status === 0;++ if (merge.status !== 0 && !mergeInProgress) {+ const details = [merge.stdout, merge.stderr]+ .map((value) => value.trim())+ .filter(Boolean)+ .join("\n");+ throw new Error(+ `Could not start the customized upstream merge${details ? `:\n${details}` : ""}`,+ );+ }++ restoreProtectedWorkflows(cwd, baseCommit);+ const unresolved = runGit(["diff", "--name-only", "--diff-filter=U"], { cwd })+ .stdout.trim()+ .split("\n")+ .filter(Boolean);++ if (unresolved.length > 0) {+ throw new Error(`Customized fork conflicts with upstream in: ${unresolved.join(", ")}`);+ }+ if (!mergeInProgress) {+ throw new Error("Customized merge did not create a merge result");+ }++ mergedTree = runGit(["write-tree"], { cwd }).stdout.trim();+ } finally {+ runGit(["merge", "--abort"], { allowFailure: true, cwd });+ runGit(["replace", "-d", baseCommit], { allowFailure: true, cwd });+ }++ if (!mergedTree) throw new Error("Customized merge did not produce a tree");+ runGit(["read-tree", "--reset", "-u", mergedTree], { cwd });+}++export function prepareUpstreamSync({+ alignMode,+ baseRevision = "HEAD",+ cwd = process.cwd(),+ targetRevision,+}) {+ if (!targetRevision) throw new Error("targetRevision is required");+ if (!new Set(["merge", "snapshot"]).has(alignMode)) {+ throw new Error(`Unsupported upstream sync align mode: ${alignMode}`);+ }++ const trackedStatus = runGit(["status", "--porcelain=v1", "--untracked-files=no"], { cwd })+ .stdout.trim();+ if (trackedStatus) {+ throw new Error(`Upstream sync requires a clean tracked worktree:\n${trackedStatus}`);+ }++ const baseCommit = resolveCommit(cwd, baseRevision);+ const targetCommit = resolveCommit(cwd, targetRevision);++ if (alignMode === "snapshot") {+ prepareSnapshot(cwd, baseCommit, targetCommit);+ } else {+ prepareCustomizedMerge(cwd, baseCommit, targetCommit);+ }++ requireNoWorkflowChanges(cwd, baseCommit);+ requirePreparedChanges(cwd, baseCommit);++ return { alignMode, baseCommit, targetCommit };+}++function runCli() {+ if (process.argv[2] !== "prepare") {+ throw new Error("Usage: node scripts/prepare-upstream-sync.mjs prepare");+ }++ const result = prepareUpstreamSync({+ alignMode: process.env.EDGE_SYNC_ALIGN_MODE,+ baseRevision: process.env.EDGE_SYNC_BASE_COMMIT || "HEAD",+ targetRevision: process.env.EDGE_SYNC_TARGET_COMMIT,+ });+ process.stdout.write(+ `[ok] prepared ${result.alignMode} update ${result.baseCommit.slice(0, 12)} -> ${result.targetCommit.slice(0, 12)} without changing ${protectedWorkflowPath}\n`,+ );+}++const invokedPath = process.argv[1] ? resolve(process.argv[1]) : "";+if (invokedPath === fileURLToPath(import.meta.url)) {+ runCli();+}diff --git a/scripts/upstream-sync-plan.mjs b/scripts/upstream-sync-plan.mjsindex 1467c8e0..2c558155 100644--- a/scripts/upstream-sync-plan.mjs+++ b/scripts/upstream-sync-plan.mjs@@ -29,16 +29,16 @@ export function decideUpstreamSync({if (!preserveForkChanges) {if (headIsAncestorOfTarget) {- return update("reset", "behind_target");+ return update("snapshot", "behind_target");}if (targetIsAncestorOfHead) {- return update("reset", "deploy_mirror_ahead");+ return update("snapshot", "deploy_mirror_ahead");}- return update("reset", "deploy_mirror_reset");+ return update("snapshot", "deploy_mirror_reset");}if (headIsAncestorOfTarget) {- return update("reset", "behind_target");+ return update("snapshot", "behind_target");}if (targetIsAncestorOfHead) {return noUpdate("customized_contains_target", forceRedeploy);diff --git a/tests/deployment-entrypoints.test.ts b/tests/deployment-entrypoints.test.tsindex 62025653..9d8125d6 100644--- a/tests/deployment-entrypoints.test.ts+++ b/tests/deployment-entrypoints.test.ts@@ -33,6 +33,51 @@ const extractSection = (document: string, sectionHeading: string) => {};const normalizeMarkdownCopy = (value: string) =>value.replace(/[`*]/g, "").replace(/\s+/g, " ").trim();+const runFixtureGit = (cwd: string, ...args: string[]) => {+ const result = spawnSync("git", args, { cwd, encoding: "utf8" });+ if (result.error) throw result.error;+ if (result.status !== 0) {+ throw new Error(+ `git ${args.join(" ")} failed:\n${result.stdout.trim()}\n${result.stderr.trim()}`,+ );+ }+};+const fixtureGitStatus = (cwd: string, ...args: string[]) =>+ spawnSync("git", args, { cwd, encoding: "utf8" }).status;+const writeFixtureFile = (cwd: string, path: string, content: string) => {+ const absolutePath = resolve(cwd, path);+ mkdirSync(resolve(absolutePath, ".."), { recursive: true });+ writeFileSync(absolutePath, content);+};+const initializeSyncFixture = (cwd: string) => {+ runFixtureGit(cwd, "init", "-b", "main");+ runFixtureGit(cwd, "config", "user.name", "EdgeEver Test");+ runFixtureGit(cwd, "config", "user.email", "[email protected]");+};+const prepareFixtureUpstreamSync = (+ cwd: string,+ alignMode: "merge" | "snapshot",+ targetRevision: string,+) => {+ const result = spawnSync(+ "node",+ [resolve(repositoryRoot, "scripts/prepare-upstream-sync.mjs"), "prepare"],+ {+ cwd,+ encoding: "utf8",+ env: {+ ...process.env,+ EDGE_SYNC_ALIGN_MODE: alignMode,+ EDGE_SYNC_BASE_COMMIT: "HEAD",+ EDGE_SYNC_TARGET_COMMIT: targetRevision,+ },+ },+ );+ if (result.error) throw result.error;+ if (result.status !== 0) {+ throw new Error(`prepare-upstream-sync failed:\n${result.stdout}\n${result.stderr}`);+ }+};describe("Cloudflare deployment entrypoints", () => {test("all entrypoints converge on the common deployment pipeline", () => {@@ -268,10 +313,11 @@ describe("Cloudflare deployment entrypoints", () => {expect(workflow).toContain(scripts.test);expect(workflow.match(/if: steps\.upstream\.outputs\.align_mode == 'merge'/g)).toHaveLength(2);expect(workflow).toContain("git push origin HEAD:main");- expect(workflow).toContain("git push --force-with-lease origin HEAD:main");- expect(workflow).toContain('if [ "${REASON}" = "behind_target" ]');- expect(workflow).toContain("mode=fast_forward");- expect(workflow).toContain("git reset --hard");+ expect(workflow).not.toContain("git push --force-with-lease origin HEAD:main");+ expect(workflow).not.toContain("git reset --hard");+ expect(workflow).toContain("scripts/prepare-upstream-sync.mjs");+ expect(workflow).toContain("':(exclude).github/workflows/**'");+ expect(workflow).toContain("Refusing to publish an update that changes downstream");expect(workflow).toContain("content_matches_target");expect(workflow).toContain("already_on_target");expect(workflow).toContain("fork_mode=mirror");@@ -316,14 +362,14 @@ describe("Cloudflare deployment entrypoints", () => {targetIsAncestorOfHead: false,}),).toEqual({- alignMode: "reset",+ alignMode: "snapshot",reason: "deploy_mirror_reset",republishOnly: false,updateRequired: true,});});- test("resets a deploy mirror that moved ahead of the stable release", () => {+ test("snapshots a deploy mirror that moved ahead of the stable release", () => {expect(decideUpstreamSync({contentMatchesTarget: false,@@ -334,7 +380,7 @@ describe("Cloudflare deployment entrypoints", () => {targetIsAncestorOfHead: true,}),).toEqual({- alignMode: "reset",+ alignMode: "snapshot",reason: "deploy_mirror_ahead",republishOnly: false,updateRequired: true,@@ -377,6 +423,212 @@ describe("Cloudflare deployment entrypoints", () => {});});+ test("prepares a linear product snapshot without changing downstream workflows", () => {+ const workingDirectory = mkdtempSync(resolve(tmpdir(), "edgeever-upstream-snapshot-"));++ try {+ initializeSyncFixture(workingDirectory);+ writeFixtureFile(workingDirectory, "app.txt", "base\n");+ writeFixtureFile(workingDirectory, "removed.txt", "remove me\n");+ writeFixtureFile(+ workingDirectory,+ ".github/workflows/sync-edgeever-upstream.yml",+ "name: downstream base\n",+ );+ runFixtureGit(workingDirectory, "add", ".");+ runFixtureGit(workingDirectory, "commit", "-m", "base");++ runFixtureGit(workingDirectory, "checkout", "-b", "upstream");+ writeFixtureFile(workingDirectory, "app.txt", "upstream target\n");+ writeFixtureFile(workingDirectory, "added.txt", "added upstream\n");+ writeFixtureFile(+ workingDirectory,+ ".github/workflows/sync-edgeever-upstream.yml",+ "name: upstream changed\n",+ );+ writeFixtureFile(+ workingDirectory,+ ".github/workflows/windows-test-signing.yml",+ "name: official only\n",+ );+ rmSync(resolve(workingDirectory, "removed.txt"));+ runFixtureGit(workingDirectory, "add", "-A");+ runFixtureGit(workingDirectory, "commit", "-m", "upstream target");++ runFixtureGit(workingDirectory, "checkout", "-b", "downstream", "main");+ writeFixtureFile(workingDirectory, "app.txt", "stale downstream product\n");+ writeFixtureFile(+ workingDirectory,+ ".github/workflows/sync-edgeever-upstream.yml",+ "name: downstream updater\n",+ );+ runFixtureGit(workingDirectory, "add", ".");+ runFixtureGit(workingDirectory, "commit", "-m", "downstream state");+ runFixtureGit(workingDirectory, "tag", "downstream-base");++ prepareFixtureUpstreamSync(workingDirectory, "snapshot", "upstream");++ expect(readFileSync(resolve(workingDirectory, "app.txt"), "utf8")).toBe(+ "upstream target\n",+ );+ expect(readFileSync(resolve(workingDirectory, "added.txt"), "utf8")).toBe(+ "added upstream\n",+ );+ expect(readFileSync(resolve(+ workingDirectory,+ ".github/workflows/sync-edgeever-upstream.yml",+ ), "utf8")).toBe("name: downstream updater\n");+ expect(readdirSync(resolve(workingDirectory, ".github/workflows"))).toEqual([+ "sync-edgeever-upstream.yml",+ ]);+ expect(fixtureGitStatus(+ workingDirectory,+ "diff",+ "--cached",+ "--quiet",+ "--",+ ".github/workflows",+ )).toBe(0);++ runFixtureGit(workingDirectory, "commit", "-m", "sync upstream product");+ expect(fixtureGitStatus(workingDirectory, "diff", "--quiet", "downstream-base", "HEAD^"))+ .toBe(0);+ expect(fixtureGitStatus(workingDirectory, "rev-parse", "--verify", "HEAD^2"))+ .not.toBe(0);+ expect(fixtureGitStatus(+ workingDirectory,+ "diff",+ "--quiet",+ "upstream",+ "HEAD",+ "--",+ ".",+ ":(exclude).github/workflows/**",+ )).toBe(0);+ expect(fixtureGitStatus(+ workingDirectory,+ "diff",+ "--quiet",+ "downstream-base",+ "HEAD",+ "--",+ ".github/workflows",+ )).toBe(0);+ } finally {+ rmSync(workingDirectory, { force: true, recursive: true });+ }+ });++ test("flattens customized merges and preserves their downstream workflows", () => {+ const workingDirectory = mkdtempSync(resolve(tmpdir(), "edgeever-upstream-merge-"));++ try {+ initializeSyncFixture(workingDirectory);+ writeFixtureFile(workingDirectory, "upstream.txt", "base\n");+ writeFixtureFile(workingDirectory, "custom.txt", "base\n");+ writeFixtureFile(+ workingDirectory,+ ".github/workflows/sync-edgeever-upstream.yml",+ "name: base\n",+ );+ runFixtureGit(workingDirectory, "add", ".");+ runFixtureGit(workingDirectory, "commit", "-m", "base");++ runFixtureGit(workingDirectory, "checkout", "-b", "upstream");+ writeFixtureFile(workingDirectory, "upstream.txt", "upstream target\n");+ writeFixtureFile(+ workingDirectory,+ ".github/workflows/sync-edgeever-upstream.yml",+ "name: upstream workflow\n",+ );+ runFixtureGit(workingDirectory, "add", ".");+ runFixtureGit(workingDirectory, "commit", "-m", "upstream target");+ runFixtureGit(workingDirectory, "tag", "upstream-v1");++ runFixtureGit(workingDirectory, "checkout", "-b", "downstream", "main");+ writeFixtureFile(workingDirectory, "custom.txt", "downstream customization\n");+ writeFixtureFile(+ workingDirectory,+ ".github/workflows/sync-edgeever-upstream.yml",+ "name: downstream updater\n",+ );+ runFixtureGit(workingDirectory, "add", ".");+ runFixtureGit(workingDirectory, "commit", "-m", "customized downstream");+ runFixtureGit(workingDirectory, "tag", "downstream-base");++ prepareFixtureUpstreamSync(workingDirectory, "merge", "upstream-v1");++ expect(readFileSync(resolve(workingDirectory, "upstream.txt"), "utf8")).toBe(+ "upstream target\n",+ );+ expect(readFileSync(resolve(workingDirectory, "custom.txt"), "utf8")).toBe(+ "downstream customization\n",+ );+ expect(readFileSync(resolve(+ workingDirectory,+ ".github/workflows/sync-edgeever-upstream.yml",+ ), "utf8")).toBe("name: downstream updater\n");++ runFixtureGit(+ workingDirectory,+ "commit",+ "-m",+ "sync customized fork",+ "-m",+ "EdgeEver-Upstream-Commit: upstream-v1",+ );+ expect(fixtureGitStatus(workingDirectory, "diff", "--quiet", "downstream-base", "HEAD^"))+ .toBe(0);+ expect(fixtureGitStatus(workingDirectory, "rev-parse", "--verify", "HEAD^2"))+ .not.toBe(0);+ expect(fixtureGitStatus(+ workingDirectory,+ "diff",+ "--quiet",+ "downstream-base",+ "HEAD",+ "--",+ ".github/workflows",+ )).toBe(0);++ runFixtureGit(workingDirectory, "checkout", "upstream");+ writeFixtureFile(workingDirectory, "upstream.txt", "upstream target v2\n");+ writeFixtureFile(+ workingDirectory,+ ".github/workflows/sync-edgeever-upstream.yml",+ "name: upstream workflow v2\n",+ );+ runFixtureGit(workingDirectory, "add", ".");+ runFixtureGit(workingDirectory, "commit", "-m", "upstream target v2");+ runFixtureGit(workingDirectory, "tag", "upstream-v2");+ runFixtureGit(workingDirectory, "checkout", "downstream");+ prepareFixtureUpstreamSync(workingDirectory, "merge", "upstream-v2");++ expect(readFileSync(resolve(workingDirectory, "upstream.txt"), "utf8")).toBe(+ "upstream target v2\n",+ );+ expect(readFileSync(resolve(workingDirectory, "custom.txt"), "utf8")).toBe(+ "downstream customization\n",+ );+ expect(readFileSync(resolve(+ workingDirectory,+ ".github/workflows/sync-edgeever-upstream.yml",+ ), "utf8")).toBe("name: downstream updater\n");+ runFixtureGit(+ workingDirectory,+ "commit",+ "-m",+ "sync customized fork v2",+ "-m",+ "EdgeEver-Upstream-Commit: upstream-v2",+ );+ expect(fixtureGitStatus(workingDirectory, "rev-parse", "--verify", "HEAD^2"))+ .not.toBe(0);+ } finally {+ rmSync(workingDirectory, { force: true, recursive: true });+ }+ });+test("public deployment documentation exposes only Fork and Agent paths", () => {const englishReadme = readRepositoryFile("README.md");const chineseReadme = readRepositoryFile("README.zh-CN.md");