@gobing-ai/knowledge-kit 0.1.10 → 0.1.11

package/plugins/publishings/surfdash-pub/dist/index.js

@@ -12070,6 +12070,7 @@ class FakeFileCliTransport {
 var init_src = () => {};
 
 // ../../plugins/publishings/surfdash-pub/src/index.ts
+import { createHash } from "crypto";
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { copyFile, cp, writeFile } from "fs/promises";
 import { dirname as dirname3, extname, isAbsolute, join as join2, relative, resolve, sep as sep2 } from "path";
@@ -12463,7 +12464,47 @@ var DIGEST_TAG = "sub-category:ai-daily";
 var PODCAST_INTROS = ["\u8FD9\u91CC\u662F\u7531Robin", "\u54B8\u8BDD\u54B8\u8BF4", "This is Robin", "Robin \u304C\u304A\u5C4A\u3051"];
 var SEO_TITLE_LIMIT = 60;
 var KEY_LINE = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/;
+var BLOCK_SCALAR = /^[>|][+-]?$/;
 var escapeRe = (token) => token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function leadingIndent(line) {
+  return line.match(/^[ \t]*/)?.[0].length ?? 0;
+}
+function readBlockScalar(lines, start, end, parentIndent, indicator) {
+  const content = [];
+  let j = start;
+  while (j < end) {
+    const line = lines[j] ?? "";
+    if (line.trim() === "") {
+      content.push("");
+      j++;
+      continue;
+    }
+    if (leadingIndent(line) <= parentIndent)
+      break;
+    content.push(line);
+    j++;
+  }
+  if (content.length === 0)
+    return { value: "", nextIndex: j };
+  const normalized = content.map((line) => line === "" ? "" : line.slice(Math.min(parentIndent, leadingIndent(line))));
+  try {
+    const parsed = Bun.YAML.parse([`value: ${indicator}`, ...normalized, "sentinel: null"].join(`
+`));
+    if (typeof parsed.value === "string")
+      return { value: parsed.value, nextIndex: j };
+  } catch {}
+  const folded = indicator.startsWith(">");
+  const parts = [];
+  for (const line of normalized) {
+    if (line !== "")
+      parts.push(line.trim());
+  }
+  return {
+    value: parts.join(folded ? " " : `
+`),
+    nextIndex: j
+  };
+}
 function unquote(value) {
   if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
     try {
@@ -12494,28 +12535,33 @@ function parseFrontmatterScalars(markdown) {
       continue;
     const key = match[1];
     const value = match[2].trim();
-    if (value === ">-" || value === ">" || value === ">+" || value === "|-" || value === "|") {
-      const parts = [];
-      let j = i + 1;
-      while (j < end) {
-        const continuation = lines[j];
-        if (!continuation || !/^[ \t]+\S/.test(continuation))
-          break;
-        parts.push(continuation.trim());
-        j++;
-      }
-      out.set(key, parts.join(" "));
-      i = j - 1;
+    if (BLOCK_SCALAR.test(value)) {
+      const block = readBlockScalar(lines, i + 1, end, leadingIndent(line), value);
+      out.set(key, block.value);
+      i = block.nextIndex - 1;
       continue;
     }
     if (value === "") {
       const items = [];
+      let listIndent;
       let j = i + 1;
       while (j < end) {
         const itemLine = lines[j];
         if (!itemLine || !/^\s*-\s+/.test(itemLine))
           break;
-        items.push(unquote(itemLine.replace(/^\s*-\s+/, "").trim()));
+        const itemIndent = leadingIndent(itemLine);
+        if (listIndent === undefined)
+          listIndent = itemIndent;
+        if (itemIndent !== listIndent)
+          break;
+        const raw = itemLine.replace(/^\s*-\s+/, "").trim();
+        if (BLOCK_SCALAR.test(raw)) {
+          const block = readBlockScalar(lines, j + 1, end, itemIndent, raw);
+          items.push(block.value);
+          j = block.nextIndex;
+          continue;
+        }
+        items.push(unquote(raw));
         j++;
       }
       if (items.length > 0) {
@@ -12626,7 +12672,15 @@ function checkDigestFrontmatter(markdown, locale) {
 
 // ../../plugins/publishings/surfdash-pub/src/index.ts
 var TARGET = "surfdash";
-var OPERATIONS = ["publish", "scaffold-locale", "sync", "patch"];
+var OPERATIONS = [
+  "publish",
+  "prepare",
+  "refine-prepared",
+  "publish-prepared",
+  "scaffold-locale",
+  "sync",
+  "patch"
+];
 var SCAFFOLD_LOCALES = ["en", "ja"];
 var COVER_EXTS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"]);
 function slugify2(str) {
@@ -12681,6 +12735,15 @@ function isDigestContent(content) {
 function fail(error) {
   return ResultSchema.parse({ ok: false, target: TARGET, error });
 }
+function failWithDeliveryState(error, deliveryState) {
+  return ResultSchema.parse({ ok: false, target: TARGET, error, metadata: { deliveryState } });
+}
+function failNotSent(error) {
+  return failWithDeliveryState(error, "not-sent");
+}
+function failUncertain(error) {
+  return failWithDeliveryState(error, "uncertain");
+}
 async function writePublishResult(outputPath, result) {
   const outDir = dirname3(outputPath);
   if (outDir && outDir !== ".") {
@@ -12785,6 +12848,8 @@ function requireRefined(filePath) {
   return `surfdash refine step did not run for ${filePath} (no \`refined: true\`): the publishing pipeline is broken \u2014 the post would ship with generator-supplied SEO metadata`;
 }
 function digestCheckGate(filePath, locale) {
+  if (process.env.SURFDASH_DIGEST_CHECK === "off")
+    return;
   const problems = checkDigestFrontmatter(readFileSync2(filePath, "utf-8"), locale);
   if (problems.length === 0)
     return;
@@ -12795,8 +12860,69 @@ function digestCheckGate(filePath, locale) {
   }
   return `digest frontmatter check failed: ${problems.join("; ")}`;
 }
-async function pushPostGit(surfdashRoot, relPostDir, message) {
-  return commitPostPaths(surfdashRoot, [relPostDir], message);
+function parsePorcelainPaths(stdout) {
+  return stdout.split(`
+`).map((line) => line.trimEnd()).filter((line) => line.length > 3).map((line) => {
+    const raw = line.slice(3).trim();
+    const arrowIdx = raw.indexOf(" -> ");
+    const target = arrowIdx >= 0 ? raw.slice(arrowIdx + 4).trim() : raw;
+    if (target.startsWith('"') && target.endsWith('"')) {
+      return target.slice(1, -1);
+    }
+    return target;
+  }).filter((p) => p.length > 0);
+}
+async function runListenLinkBackfill(surfdashRoot) {
+  if (process.env.SURFDASH_LISTEN_BACKFILL === "off") {
+    return [];
+  }
+  const before = await spawnCli(["git", "status", "--porcelain", "--", "content/posts"], surfdashRoot);
+  const beforePaths = new Set(parsePorcelainPaths(before.stdout));
+  const spawned = await spawnCli(["bun", "run", "sd", "seo", "listen-link", "--backfill", "--write"], surfdashRoot);
+  if (spawned.exitCode !== 0) {
+    echoError(`listen-link backfill: ${cliErrorText(spawned)}`);
+  }
+  const after = await spawnCli(["git", "status", "--porcelain", "--", "content/posts"], surfdashRoot);
+  const afterPaths = parsePorcelainPaths(after.stdout);
+  return [...new Set(afterPaths.filter((p) => !beforePaths.has(p)))];
+}
+var SITE_GATE_COMMANDS = [
+  ["bun", "run", "sd", "check", "digest"],
+  ["bun", "run", "check:content"]
+];
+function extractFailingPostHint(text) {
+  const match = text.match(/(?:content[\\/])?posts[\\/][^\s:)]+/);
+  if (!match)
+    return;
+  return match[0].replace(/[.,;]+$/, "");
+}
+async function runSiteGate(surfdashRoot) {
+  if (process.env.SURFDASH_DIGEST_CHECK === "off") {
+    return { ok: true };
+  }
+  for (const cmd of SITE_GATE_COMMANDS) {
+    const spawned = await spawnCli([...cmd], surfdashRoot);
+    if (spawned.exitCode !== 0) {
+      const output = cliErrorText(spawned);
+      const postHint = extractFailingPostHint(output);
+      const hint = postHint ? ` [failing post: ${postHint}]` : "";
+      const error = `site gate failed: ${cmd.join(" ")} (exit ${spawned.exitCode})${hint}: ${output}`;
+      if (process.env.SURFDASH_DIGEST_CHECK === "warn") {
+        for (const line of error.split(`
+`)) {
+          echoError(`site gate (warn): ${line}`);
+        }
+        continue;
+      }
+      return { ok: false, error };
+    }
+  }
+  return { ok: true };
+}
+async function pushPostGit(surfdashRoot, relPostDir, message, extraPaths = []) {
+  const rawPaths = Array.isArray(relPostDir) ? [...relPostDir, ...extraPaths] : [relPostDir, ...extraPaths];
+  const paths = [...new Set(rawPaths)];
+  return commitPostPaths(surfdashRoot, paths, message);
 }
 async function assertMainBranch(surfdashRoot) {
   const branch = await spawnCli(["git", "rev-parse", "--abbrev-ref", "HEAD"], surfdashRoot);
@@ -12912,7 +13038,19 @@ async function scaffoldLocale(options) {
     return fail(`options.postPath must be a zh post path containing a "${sep2}zh${sep2}" segment: ${postPath.postPath}`);
   }
   try {
-    const spawned = await spawnCli(["bun", "run", "sd", "translate", postPath.postPath, "--source", "zh", "--target", target.locale], surfdashRoot);
+    const force = options.force === true;
+    const spawned = await spawnCli([
+      "bun",
+      "run",
+      "sd",
+      "translate",
+      postPath.postPath,
+      "--source",
+      "zh",
+      "--target",
+      target.locale,
+      ...force ? ["--force"] : []
+    ], surfdashRoot);
     if (spawned.exitCode !== 0) {
       return fail(`sd translate failed (exit ${spawned.exitCode}): ${cliErrorText(spawned)}`);
     }
@@ -13030,6 +13168,14 @@ async function patchPost(options) {
       commitPaths.add(relative(surfdashRoot, assetsDir));
     }
   }
+  if (process.env.SURFDASH_AUTO_PUSH !== "0") {
+    const backfilled = await runListenLinkBackfill(surfdashRoot);
+    for (const p of backfilled)
+      commitPaths.add(p);
+    const gate = await runSiteGate(surfdashRoot);
+    if (!gate.ok)
+      return fail(gate.error);
+  }
   const commit = await commitPostPaths(surfdashRoot, [...commitPaths], `feat: cover + podcast cross-link for ${outcome.slug} (kk daily patch)`, process.env.SURFDASH_AUTO_PUSH !== "0");
   if (!commit.ok)
     return fail(`patch: ${commit.error}`);
@@ -13056,94 +13202,347 @@ async function patchPost(options) {
     metadata
   });
 }
-async function publishPost(payload) {
-  const postsurfingBin = process.env.POSTSURFING_BIN ?? "postsurfing";
+function fileSha256(filePath) {
+  return createHash("sha256").update(readFileSync2(filePath)).digest("hex");
+}
+function preparedLocaleIdentity(postPath, runDate) {
+  const enPath = deriveLocaleDraftPath(postPath, "en");
+  const jaPath = deriveLocaleDraftPath(postPath, "ja");
+  if (enPath === undefined || jaPath === undefined) {
+    return { ok: false, error: `prepared zh post path must contain a "/zh/" locale segment: ${postPath}` };
+  }
+  const localePaths = { zh: postPath, en: enPath, ja: jaPath };
+  const localeDigests = {};
+  for (const locale of ["zh", "en", "ja"]) {
+    const path = localePaths[locale];
+    if (!existsSync2(path))
+      return { ok: false, error: `${locale} locale file is missing: ${path}` };
+    try {
+      localeDigests[locale] = fileSha256(path);
+    } catch (error) {
+      return {
+        ok: false,
+        error: `${locale} locale file cannot be fingerprinted: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+  }
+  const identity = { runDate, postPath, localePaths, localeDigests };
+  return {
+    ok: true,
+    value: { ...identity, fingerprint: createHash("sha256").update(JSON.stringify(identity)).digest("hex") }
+  };
+}
+function resolvePreparedLocaleSet(options) {
+  const postPath = resolvePostPath(options);
+  if ("error" in postPath)
+    return { ok: false, result: failNotSent(postPath.error) };
   const surfdashRoot = resolveSurfdashRoot();
   if (!surfdashRoot) {
-    return fail("SURFDASH_ROOT is required when POSTSURFING_BIN is not a path inside the surfdash checkout");
+    return {
+      ok: false,
+      result: failNotSent("SURFDASH_ROOT is required when POSTSURFING_BIN is not a path inside the surfdash checkout")
+    };
+  }
+  const outsideRoot = postPathOutsideRoot(postPath.postPath, surfdashRoot);
+  if (outsideRoot)
+    return { ok: false, result: failNotSent(outsideRoot) };
+  if (!existsSync2(postPath.postPath))
+    return { ok: false, result: failNotSent(`prepared post does not exist: ${postPath.postPath}`) };
+  const runDate = options.runDate;
+  if (typeof runDate !== "string" || !/^\d{8}$/.test(runDate)) {
+    return { ok: false, result: failNotSent(`options.runDate must be YYYYMMDD, got '${String(runDate)}'`) };
   }
-  const locale = process.env.SURFDASH_LOCALE ?? "zh";
-  if (!["zh", "en", "ja"].includes(locale)) {
-    return fail(`SURFDASH_LOCALE must be one of zh/en/ja, got '${locale}'`);
+  const articlesRoot = resolve(surfdashRoot, "content", "posts", "articles");
+  const relativePost = relative(articlesRoot, postPath.postPath);
+  const parts = relativePost.split(sep2);
+  const slug = parts[1];
+  if (parts.length !== 3 || parts[0] !== "zh" || parts[2] !== "index.md" || slug === undefined || slug === "") {
+    return {
+      ok: false,
+      result: failNotSent(`options.postPath must be content/posts/articles/zh/<slug>/index.md: ${postPath.postPath}`)
+    };
+  }
+  const enPath = deriveLocaleDraftPath(postPath.postPath, "en");
+  const jaPath = deriveLocaleDraftPath(postPath.postPath, "ja");
+  if (enPath === undefined || jaPath === undefined) {
+    return {
+      ok: false,
+      result: failNotSent(`prepared zh post path must contain a "/zh/" locale segment: ${postPath.postPath}`)
+    };
   }
+  const localePaths = { zh: postPath.postPath, en: enPath, ja: jaPath };
+  for (const locale of ["zh", "en", "ja"]) {
+    if (!existsSync2(localePaths[locale])) {
+      return { ok: false, result: failNotSent(`${locale} locale file is missing: ${localePaths[locale]}`) };
+    }
+  }
+  return { ok: true, value: { surfdashRoot, runDate, postPath: postPath.postPath, slug, localePaths } };
+}
+function resolvePreparedPost(options) {
+  const resolved = resolvePreparedLocaleSet(options);
+  if (!resolved.ok)
+    return resolved;
+  const { surfdashRoot, runDate, postPath: preparedPath, slug } = resolved.value;
+  const expectedPostSha256 = options.expectedPostSha256;
+  if (typeof expectedPostSha256 !== "string" || !/^[0-9a-f]{64}$/.test(expectedPostSha256)) {
+    return { ok: false, result: failNotSent("options.expectedPostSha256 must be a lowercase SHA-256 digest") };
+  }
+  const expectedLocaleFingerprint = options.expectedLocaleFingerprint;
+  if (typeof expectedLocaleFingerprint !== "string" || !/^[0-9a-f]{64}$/.test(expectedLocaleFingerprint)) {
+    return {
+      ok: false,
+      result: failNotSent("options.expectedLocaleFingerprint must be a lowercase SHA-256 digest")
+    };
+  }
+  const identity = preparedLocaleIdentity(preparedPath, runDate);
+  if (!identity.ok)
+    return { ok: false, result: failNotSent(identity.error) };
+  if (identity.value.localeDigests.zh !== expectedPostSha256) {
+    return {
+      ok: false,
+      result: failNotSent(`prepared zh post bytes changed after validation: ${preparedPath}`)
+    };
+  }
+  if (identity.value.fingerprint !== expectedLocaleFingerprint) {
+    return {
+      ok: false,
+      result: failNotSent("prepared locale files changed after validation; refresh the locale gate before publishing")
+    };
+  }
+  const baseUrl = (process.env.SURFDASH_URL ?? "https://surfing.salty.vip").replace(/\/$/, "");
+  return {
+    ok: true,
+    prepared: {
+      surfdashRoot,
+      locale: "zh",
+      dateStamp: runDate,
+      slug,
+      filePath: preparedPath,
+      relPostDir: join2("content", "posts", "articles", "zh", slug),
+      relPostDirs: ["zh", "en", "ja"].map((locale) => join2("content", "posts", "articles", locale, slug)),
+      articleUrl: `${baseUrl}/zh/posts/${slug}`
+    },
+    identity: identity.value
+  };
+}
+async function preparePost(payload) {
+  const surfdashRoot = resolveSurfdashRoot();
+  if (!surfdashRoot) {
+    return {
+      ok: false,
+      result: failNotSent("SURFDASH_ROOT is required when POSTSURFING_BIN is not a path inside the surfdash checkout")
+    };
+  }
+  const rawLocale = process.env.SURFDASH_LOCALE ?? "zh";
+  if (!["zh", "en", "ja"].includes(rawLocale)) {
+    return { ok: false, result: failNotSent(`SURFDASH_LOCALE must be one of zh/en/ja, got '${rawLocale}'`) };
+  }
+  const locale = rawLocale;
   const runDate = typeof payload.content.metadata?.runDate === "string" ? payload.content.metadata.runDate : "";
   const today = new Date().toISOString().slice(0, 10).replaceAll("-", "");
   const dateStamp = runDate || today;
   const titleSlug = slugify2(payload.content.title ?? "");
   const slug = titleSlug ? `${dateStamp}-${titleSlug}` : `${dateStamp}-post`;
   if (runDate !== "" && !/^\d{8}$/.test(runDate)) {
-    return fail(`metadata.runDate must be YYYYMMDD, got '${runDate}'`);
+    return { ok: false, result: failNotSent(`metadata.runDate must be YYYYMMDD, got '${runDate}'`) };
   }
   const articlesRoot = resolve(surfdashRoot, "content", "posts", "articles");
   const localeRoot = resolve(articlesRoot, locale);
   const postDir = resolve(localeRoot, slug);
   if (dirname3(localeRoot) !== articlesRoot || dirname3(postDir) !== localeRoot) {
-    return fail(`post path escapes ${articlesRoot}`);
+    return { ok: false, result: failNotSent(`post path escapes ${articlesRoot}`) };
   }
   const coverPath = payload.content.metadata?.coverImage;
   if (typeof coverPath === "string" && !existsSync2(coverPath)) {
-    return fail(`metadata.coverImage not found: ${coverPath}`);
+    return { ok: false, result: failNotSent(`metadata.coverImage not found: ${coverPath}`) };
   }
   if (typeof coverPath === "string" && !COVER_EXTS.has(extname(coverPath).toLowerCase())) {
-    return fail(`metadata.coverImage must be one of ${[...COVER_EXTS].join(", ")}`);
+    return {
+      ok: false,
+      result: failNotSent(`metadata.coverImage must be one of ${[...COVER_EXTS].join(", ")}`)
+    };
   }
   if (isDigestContent(payload.content) && typeof coverPath !== "string") {
-    return fail("digest post has no cover image (metadata.coverImage)");
+    return { ok: false, result: failNotSent("digest post has no cover image (metadata.coverImage)") };
   }
-  await createNodeFileSystem().ensureDir(postDir);
-  let imageFrontmatter;
-  if (typeof coverPath === "string") {
-    const assetsDir = join2(postDir, "assets");
-    await createNodeFileSystem().ensureDir(assetsDir);
-    const coverName = `cover${extname(coverPath).toLowerCase()}`;
-    await copyFile(coverPath, join2(assetsDir, coverName));
-    imageFrontmatter = `./assets/${coverName}`;
-  }
-  const markdown = mapContentToSurfingMarkdown(payload.content, {
-    image: imageFrontmatter,
-    publishDate: runDate ? `${runDate.slice(0, 4)}-${runDate.slice(4, 6)}-${runDate.slice(6, 8)}` : undefined
-  });
   const filePath = join2(postDir, "index.md");
   try {
+    await createNodeFileSystem().ensureDir(postDir);
+    let imageFrontmatter;
+    if (typeof coverPath === "string") {
+      const assetsDir = join2(postDir, "assets");
+      await createNodeFileSystem().ensureDir(assetsDir);
+      const coverName = `cover${extname(coverPath).toLowerCase()}`;
+      await copyFile(coverPath, join2(assetsDir, coverName));
+      imageFrontmatter = `./assets/${coverName}`;
+    }
+    const markdown = mapContentToSurfingMarkdown(payload.content, {
+      image: imageFrontmatter,
+      publishDate: runDate ? `${runDate.slice(0, 4)}-${runDate.slice(4, 6)}-${runDate.slice(6, 8)}` : undefined
+    });
     await createNodeFileSystem().writeFile(filePath, markdown);
+  } catch (err) {
+    return {
+      ok: false,
+      result: failNotSent(`Surfdash post preparation failed: ${err instanceof Error ? err.message : String(err)}`)
+    };
+  }
+  const baseUrl = (process.env.SURFDASH_URL ?? "https://surfing.salty.vip").replace(/\/$/, "");
+  const articleUrl = `${baseUrl}${locale === "en" ? "" : `/${locale}`}/posts/${slug}`;
+  return {
+    ok: true,
+    prepared: {
+      surfdashRoot,
+      locale,
+      dateStamp,
+      slug,
+      filePath,
+      relPostDir: join2("content", "posts", "articles", locale, slug),
+      articleUrl
+    }
+  };
+}
+async function preparePostResult(payload) {
+  const outcome = await preparePost(payload);
+  if (!outcome.ok)
+    return outcome.result;
+  return ResultSchema.parse({
+    ok: true,
+    target: TARGET,
+    message: `Prepared ${outcome.prepared.locale} post at ${outcome.prepared.filePath}`,
+    metadata: {
+      postPath: outcome.prepared.filePath,
+      articleUrl: outcome.prepared.articleUrl,
+      dateStamp: outcome.prepared.dateStamp,
+      slug: outcome.prepared.slug
+    }
+  });
+}
+async function publishPreparedFile(prepared, identity) {
+  const postsurfingBin = process.env.POSTSURFING_BIN ?? "postsurfing";
+  const { surfdashRoot, locale, dateStamp, filePath, relPostDir, relPostDirs, articleUrl } = prepared;
+  const identityMetadata = identity ? {
+    runDate: identity.runDate,
+    localeFingerprint: identity.fingerprint,
+    ...identity.postSha256 ? { postSha256: identity.postSha256 } : {}
+  } : {};
+  try {
     const spawned = await spawnCli([postsurfingBin, "publish", filePath], surfdashRoot);
     if (spawned.exitCode !== 0) {
-      return fail(`postsurfing CLI failed (exit ${spawned.exitCode}): ${withEmdashTokenHint(cliErrorText(spawned))}`);
+      return failUncertain(`postsurfing CLI failed (exit ${spawned.exitCode}): ${withEmdashTokenHint(cliErrorText(spawned))}`);
+    }
+    if (identity !== undefined) {
+      const afterRemote = preparedLocaleIdentity(filePath, identity.runDate);
+      if (!afterRemote.ok)
+        return failUncertain(`prepared locale files changed after remote publish: ${afterRemote.error}`);
+      if (afterRemote.value.fingerprint !== identity.fingerprint || identity.postSha256 !== undefined && afterRemote.value.localeDigests.zh !== identity.postSha256) {
+        return failUncertain("prepared locale files changed after remote publish; reconcile before retrying");
+      }
     }
     const notRefined = requireRefined(filePath);
     if (notRefined)
-      return fail(notRefined);
+      return failUncertain(notRefined);
     const digestProblem = digestCheckGate(filePath, locale);
     if (digestProblem)
-      return fail(digestProblem);
+      return failUncertain(digestProblem);
     const refined = readRefinedSnapshot(filePath);
-    const baseUrl = (process.env.SURFDASH_URL ?? "https://surfing.salty.vip").replace(/\/$/, "");
-    const articleUrl = `${baseUrl}${locale === "en" ? "" : `/${locale}`}/posts/${slug}`;
     if (process.env.SURFDASH_AUTO_PUSH === "0") {
       return ResultSchema.parse({
         ok: true,
         target: TARGET,
         url: articleUrl,
         message: "Published via postsurfing CLI (auto-push disabled)",
-        metadata: { postPath: filePath, refinedTitle: refined?.title, refinedCanonical: refined?.canonical }
+        metadata: {
+          postPath: filePath,
+          ...identityMetadata,
+          refinedTitle: refined?.title,
+          refinedCanonical: refined?.canonical
+        }
       });
     }
-    const relPostDir = join2("content", "posts", "articles", locale, slug);
-    const pushed = await pushPostGit(surfdashRoot, relPostDir, `content: daily AI news ${dateStamp} (zh)`);
+    const backfilled = await runListenLinkBackfill(surfdashRoot);
+    const gate = await runSiteGate(surfdashRoot);
+    if (!gate.ok)
+      return failUncertain(gate.error);
+    const commitPaths = relPostDirs ?? [relPostDir];
+    const commitLocales = relPostDirs === undefined ? [locale] : ["zh", "en", "ja"];
+    const pushed = await pushPostGit(surfdashRoot, commitPaths, `content: daily AI news ${dateStamp} (${commitLocales.join(", ")})`, backfilled);
     if (!pushed.ok)
-      return fail(pushed.error);
+      return failUncertain(pushed.error);
     const live = await awaitArticleLive(articleUrl);
     return ResultSchema.parse({
       ok: true,
       target: TARGET,
       url: articleUrl,
       message: live ? "Published, committed, pushed, and live on the site" : "Published and pushed; URL not live within the verify window \u2014 check the surfdash deploy workflow",
-      metadata: { postPath: filePath, gitCommit: pushed.hash, live, refinedTitle: refined?.title }
+      metadata: {
+        postPath: filePath,
+        ...identityMetadata,
+        gitCommit: pushed.hash,
+        live,
+        refinedTitle: refined?.title
+      }
     });
   } catch (err) {
-    return fail(`Postsurfing transport error: ${err instanceof Error ? err.message : String(err)}`);
+    return failUncertain(`Postsurfing transport error: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
+async function publishPost(payload) {
+  const outcome = await preparePost(payload);
+  if (!outcome.ok)
+    return outcome.result;
+  return publishPreparedFile(outcome.prepared);
+}
+async function refinePreparedPost(options) {
+  const resolved = resolvePreparedLocaleSet(options);
+  if (!resolved.ok)
+    return resolved.result;
+  const orchestrator = join2(resolved.value.surfdashRoot, "scripts", "publish-orchestrator.ts");
+  if (!existsSync2(orchestrator))
+    return failNotSent(`Surfdash refine orchestrator is missing: ${orchestrator}`);
+  try {
+    for (const locale of ["zh", "en", "ja"]) {
+      const filePath = resolved.value.localePaths[locale];
+      const spawned = await spawnCli([process.execPath, orchestrator, "refine", filePath], resolved.value.surfdashRoot);
+      if (spawned.exitCode !== 0) {
+        return failNotSent(`Surfdash refine failed for ${locale} (exit ${spawned.exitCode}): ${cliErrorText(spawned)}`);
+      }
+      const notRefined = requireRefined(filePath);
+      if (notRefined)
+        return failNotSent(notRefined);
+      const digestProblem = digestCheckGate(filePath, locale);
+      if (digestProblem)
+        return failNotSent(digestProblem);
+    }
+  } catch (error) {
+    return failNotSent(`Surfdash refine transport error: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const identity = preparedLocaleIdentity(resolved.value.postPath, resolved.value.runDate);
+  if (!identity.ok)
+    return failNotSent(identity.error);
+  return ResultSchema.parse({
+    ok: true,
+    target: TARGET,
+    message: "Refined zh/en/ja via the Surfdash-owned orchestrator",
+    metadata: {
+      postPath: resolved.value.postPath,
+      runDate: resolved.value.runDate,
+      localePaths: identity.value.localePaths,
+      localeDigests: identity.value.localeDigests,
+      localeFingerprint: identity.value.fingerprint
+    }
+  });
+}
+async function publishPreparedPost(options) {
+  const outcome = resolvePreparedPost(options);
+  if (!outcome.ok)
+    return outcome.result;
+  return publishPreparedFile(outcome.prepared, {
+    runDate: outcome.identity.runDate,
+    fingerprint: outcome.identity.fingerprint,
+    postSha256: outcome.identity.localeDigests.zh
+  });
+}
 
 class PostsurfingFileCliTransport {
   kind = "file-cli";
@@ -13153,6 +13552,12 @@ class PostsurfingFileCliTransport {
     if ("error" in routed)
       return fail(routed.error);
     switch (routed.operation) {
+      case "prepare":
+        return preparePostResult(payload);
+      case "refine-prepared":
+        return refinePreparedPost(options);
+      case "publish-prepared":
+        return publishPreparedPost(options);
       case "scaffold-locale":
         return scaffoldLocale(options);
       case "sync":
@@ -13222,6 +13627,7 @@ export {
   commitPostPaths,
   contentTags,
   digestCheckGate,
+  extractFailingPostHint,
   fastForwardToOrigin,
   getPublishTransport,
   main2 as main,
@@ -13232,6 +13638,8 @@ export {
   pushPostGit,
   readRefinedSnapshot,
   requireRefined,
+  runListenLinkBackfill,
+  runSiteGate,
   slugify2 as slugify,
   withEmdashTokenHint
 };