fix(docs): defer localized orphan deletion

scripts/docs-sync-publish.d.mts

@@ -11,8 +11,8 @@ export function parseArgs(argv: unknown): {
  * Resolves the local ClawHub repository path used for docs mirroring.
  */
 export function resolveClawHubRepoPath(value?: string, options?: Record<string, unknown>): string;
-/** Removes locale pages whose canonical source page no longer exists. */
-export function pruneOrphanLocaleDocs(targetDocsDir: string): void;
+/** Reports locale pages whose canonical source page no longer exists without deleting them. */
+export function reportOrphanLocaleDocs(targetDocsDir: string): number;
 /**
  * Mirrors ClawHub docs into the target docs tree.
  */

scripts/docs-sync-publish.mjs

@@ -439,31 +439,33 @@ function composeDocsConfig() {
   };
 }
 
-export function pruneOrphanLocaleDocs(targetDocsDir) {
-  let pruned = 0;
+export function reportOrphanLocaleDocs(targetDocsDir) {
+  let orphaned = 0;
   for (const locale of GENERATED_LOCALES) {
     const localeDir = path.join(targetDocsDir, locale.dir);
     if (!fs.existsSync(localeDir)) {
       continue;
     }
     for (const filePath of walkMarkdownFiles(localeDir)) {
-      const relativeToLocale = path.relative(localeDir, filePath);
+      const relativePath = path.relative(localeDir, filePath);
       // Check the assembled publish tree so externally mirrored docs, such as
       // ClawHub pages, count as valid English sources too.
-      const englishBase = path.join(targetDocsDir, relativeToLocale);
+      const englishBase = path.join(targetDocsDir, relativePath);
       const englishMd = englishBase.replace(/\.mdx?$/i, ".md");
       const englishMdx = englishBase.replace(/\.mdx?$/i, ".mdx");
       if (fs.existsSync(englishMd) || fs.existsSync(englishMdx)) {
         continue;
       }
-      fs.rmSync(filePath, { force: true });
-      pruned += 1;
+      orphaned += 1;
     }
   }
 
-  if (pruned > 0) {
-    console.log(`Pruned ${pruned} orphan localized doc(s) with no matching English source file.`);
+  if (orphaned > 0) {
+    // Translation artifacts update inbound links and delete their old target
+    // together. Docs sync must not publish the deletion ahead of that step.
+    console.log(`Deferred ${orphaned} orphan localized doc(s) to translation finalization.`);
   }
+  return orphaned;
 }
 
 function repairGeneratedLocaleDocs(targetDocsDir) {
@@ -710,7 +712,7 @@ function syncDocsTree(targetRoot, options = {}) {
     sourceRepo: options.clawhubSourceRepo,
     sourceSha: options.clawhubSourceSha,
   });
-  pruneOrphanLocaleDocs(targetDocsDir);
+  reportOrphanLocaleDocs(targetDocsDir);
   repairGeneratedLocaleDocs(targetDocsDir);
   writeJson(path.join(targetDocsDir, "docs.json"), composeDocsConfig());
   return { clawhub: clawhubSource };

test/scripts/docs-sync-publish.test.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
-import { parseArgs, pruneOrphanLocaleDocs } from "../../scripts/docs-sync-publish.mjs";
+import { parseArgs, reportOrphanLocaleDocs } from "../../scripts/docs-sync-publish.mjs";
 
 describe("docs-sync-publish", () => {
   it("parses docs sync provenance args", () => {
@@ -48,7 +48,7 @@ describe("docs-sync-publish", () => {
     }
   });
 
-  it("preserves localized pages for externally mirrored English docs", () => {
+  it("defers orphan locale deletion to translation finalization", () => {
     const docsDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-docs-sync-"));
     const mirroredEnglish = path.join(docsDir, "clawhub", "api.md");
     const localizedMirror = path.join(docsDir, "de", "clawhub", "api.md");
@@ -61,9 +61,9 @@ describe("docs-sync-publish", () => {
     fs.writeFileSync(orphan, "# Removed\n");
 
     try {
-      pruneOrphanLocaleDocs(docsDir);
+      expect(reportOrphanLocaleDocs(docsDir)).toBe(1);
       expect(fs.existsSync(localizedMirror)).toBe(true);
-      expect(fs.existsSync(orphan)).toBe(false);
+      expect(fs.existsSync(orphan)).toBe(true);
     } finally {
       fs.rmSync(docsDir, { recursive: true, force: true });
     }