@gobing-ai/knowledge-kit 0.1.9 → 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";
@@ -12345,6 +12346,10 @@ init_config();
 
 // ../../packages/kk-core/src/render-md.ts
 if (false) {}
+// ../../packages/kk-core/src/sentences.ts
+var CJK_TERMINATORS = new Set(["\u3002", "\uFF01", "\uFF1F"]);
+var LATIN_TERMINATORS = new Set([".", "!", "?"]);
+var ATTACHED_CLOSERS = new Set(["\u201D", "\u2019", "\u300D", "\u300F", "\uFF09", ")", '"', "'"]);
 // ../../plugins/publishings/surfdash-pub/src/index.ts
 init_dist();
 
@@ -12360,11 +12365,17 @@ function localeIndexPath(postPath, locale) {
     return;
   return `${postPath.slice(0, idx)}${sep}${locale}${sep}${postPath.slice(idx + marker.length)}`;
 }
+var SERIES_NAMES = {
+  zh: "\u6BCF\u65E5AI\u4E71\u7096",
+  en: "Daily AI Stew",
+  ja: "\u30C7\u30A4\u30EA\u30FCAI\u30B7\u30C1\u30E5\u30FC"
+};
 function crossLinkFor(locale, dateIso, showNotesUrl) {
+  const series = SERIES_NAMES[locale];
   const links = {
-    zh: `\uD83C\uDFA7 \u672C\u671F\u5DF2\u540C\u6B65\u5236\u4F5C\u4E3A\u64AD\u5BA2\u8282\u76EE\uFF0C[\u70B9\u51FB\u6536\u542C\u300A\u6BCF\u65E5AI\u4E71\u7096 \xB7 ${dateIso}\u300B](${showNotesUrl})\u3002`,
-    en: `\uD83C\uDFA7 This episode is also available as a podcast: [listen to \u6BCF\u65E5AI\u4E71\u7096 \xB7 ${dateIso}](${showNotesUrl}).`,
-    ja: `\uD83C\uDFA7 \u672C\u30A8\u30D4\u30BD\u30FC\u30C9\u306F\u30DD\u30C3\u30C9\u30AD\u30E3\u30B9\u30C8\u3067\u3082\u914D\u4FE1\u4E2D\uFF1A[\u6BCF\u65E5AI\u4E71\u7096 \xB7 ${dateIso} \u3092\u8074\u304F](${showNotesUrl})\u3002`
+    zh: `\uD83C\uDFA7 \u672C\u671F\u5DF2\u540C\u6B65\u5236\u4F5C\u4E3A\u64AD\u5BA2\u8282\u76EE\uFF0C[\u70B9\u51FB\u6536\u542C\u300A${series} \xB7 ${dateIso}\u300B](${showNotesUrl})\u3002`,
+    en: `\uD83C\uDFA7 This episode is also available as a podcast: [listen to ${series} \xB7 ${dateIso}](${showNotesUrl}).`,
+    ja: `\uD83C\uDFA7 \u672C\u30A8\u30D4\u30BD\u30FC\u30C9\u306F\u30DD\u30C3\u30C9\u30AD\u30E3\u30B9\u30C8\u3067\u3082\u914D\u4FE1\u4E2D\uFF1A[${series} \xB7 ${dateIso} \u3092\u8074\u304F](${showNotesUrl})\u3002`
   };
   return links[locale];
 }
@@ -12402,10 +12413,16 @@ async function patchPostFiles(request) {
     const end = frontmatterEnd(md);
     const fm = end < 0 ? md : md.slice(0, end);
     if (request.coverUrl !== "") {
+      if (!/^https:\/\//.test(request.coverUrl)) {
+        throw new Error(`coverUrl must be an absolute https:// URL, got: ${request.coverUrl}`);
+      }
       md = upsertFrontmatterKey(md, "image", request.coverUrl);
       md = upsertFrontmatterKey(md, "og_image", request.coverUrl);
       images[locale] = request.coverUrl;
-    } else if (!/^image:/m.test(fm) && await fs.exists(request.localCover)) {
+    } else if (!/^image:/m.test(fm)) {
+      if (!await fs.exists(request.localCover)) {
+        throw new Error(`${locale} post has no cover: coverUrl is empty, the frontmatter has no image key, and localCover does not exist (${request.localCover})`);
+      }
       const asset = join(dir, "assets", "cover.png");
       await fs.ensureDir(dirname2(asset));
       await fs.copy(request.localCover, asset);
@@ -12414,11 +12431,20 @@ async function patchPostFiles(request) {
       md = upsertFrontmatterKey(md, "og_image", "./assets/cover.png");
       images[locale] = "./assets/cover.png";
     }
-    if (request.showNotesUrl !== "" && !md.includes(request.showNotesUrl)) {
-      md = `${md.replace(/\s*$/, "")}
+    if (request.showNotesUrl !== "") {
+      const link = crossLinkFor(locale, request.dateIso, request.showNotesUrl);
+      const lines = md.split(`
+`);
+      const carriesUrl = lines.some((line) => line.includes(request.showNotesUrl));
+      if (!carriesUrl) {
+        md = `${md.replace(/\s*$/, "")}
 
-${crossLinkFor(locale, request.dateIso, request.showNotesUrl)}
+${link}
 `;
+      } else {
+        md = lines.map((line) => line.includes(request.showNotesUrl) && line.trimStart().startsWith("\uD83C\uDFA7") ? link : line).join(`
+`);
+      }
     }
     if (md !== before) {
       await fs.writeFile(indexMd, md);
@@ -12433,9 +12459,228 @@ ${crossLinkFor(locale, request.dateIso, request.showNotesUrl)}
   return { written, changed, absent, images, slug: basename(dirname2(request.postPath)) };
 }
 
+// ../../plugins/publishings/surfdash-pub/src/digest-check.ts
+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 {
+      return JSON.parse(value);
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1).replaceAll("''", "'");
+  }
+  return value;
+}
+function parseFrontmatterScalars(markdown) {
+  const out = new Map;
+  const lines = markdown.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---")
+    return out;
+  const end = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+  if (end < 0)
+    return out;
+  for (let i = 1;i < end; i++) {
+    const line = lines[i];
+    if (!line)
+      continue;
+    const match = line.match(KEY_LINE);
+    if (!match?.[1] || match[2] === undefined)
+      continue;
+    const key = match[1];
+    const value = match[2].trim();
+    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;
+        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) {
+        out.set(key, items);
+        i = j - 1;
+      } else {
+        out.set(key, "");
+      }
+      continue;
+    }
+    if (value.startsWith("[") && value.endsWith("]")) {
+      out.set(key, value.slice(1, -1).split(",").map((item) => unquote(item.trim())).filter((item) => item !== ""));
+      continue;
+    }
+    out.set(key, unquote(value));
+  }
+  return out;
+}
+function scalar(frontmatter, key) {
+  const value = frontmatter.get(key);
+  if (value === undefined)
+    return;
+  return Array.isArray(value) ? value.join(" ") : value;
+}
+function endsAsSentence(text, locale) {
+  return locale === "en" ? /[.!?]["')\u201D\u2019]*$/u.test(text.trimEnd()) : /[\u3002\uFF01\uFF1F][\u300D\u300F\u201D\uFF09]*$/u.test(text.trimEnd());
+}
+function checkDigestFrontmatter(markdown, locale) {
+  const frontmatter = parseFrontmatterScalars(markdown);
+  const tags = frontmatter.get("tags");
+  const tagList = Array.isArray(tags) ? tags : typeof tags === "string" && tags !== "" ? [tags] : [];
+  if (!tagList.some((tag) => tag.includes(DIGEST_TAG)))
+    return [];
+  const problems = [];
+  const series = SERIES_NAMES[locale];
+  const titleSep = locale === "en" ? ": " : "\uFF1A";
+  const listSep = locale === "en" ? ", " : "\u3001";
+  const title = scalar(frontmatter, "title");
+  if (title === undefined || title === "") {
+    problems.push("title: missing");
+  } else {
+    const match = title.match(new RegExp(`^${escapeRe(series)} \xB7 (\\d{4}-\\d{2}-\\d{2})${escapeRe(titleSep)}(.+)$`));
+    if (!match) {
+      problems.push(`title: expected "<series> \xB7 YYYY-MM-DD${titleSep}<h1>${listSep}<h2>" for ${series}, got "${title}"`);
+    } else {
+      const rest = match[2] ?? "";
+      const heads = locale === "en" ? rest.split(", ") : rest.split("\u3001");
+      const seps = locale === "en" ? (rest.match(/, /g) ?? []).length : (rest.match(/\u3001/g) ?? []).length;
+      if (seps !== 1 || heads.some((head) => head.trim() === "")) {
+        problems.push(`title: expected exactly two non-empty headlines joined "${listSep}", got "${rest}"`);
+      }
+    }
+    const seoTitle = `${title} | Surfing`;
+    const seoLength = Array.from(seoTitle).length;
+    if (seoLength > SEO_TITLE_LIMIT) {
+      problems.push(`title: "${seoTitle}" is ${seoLength} code points (max ${SEO_TITLE_LIMIT})`);
+    }
+    if (title.includes("\u2026") || title.includes("..."))
+      problems.push('title: contains "\u2026" or "..."');
+  }
+  const description = scalar(frontmatter, "description");
+  const [min, max] = locale === "en" ? [120, 155] : [70, 100];
+  if (description === undefined || description === "") {
+    problems.push("description: missing");
+  } else {
+    const length = Array.from(description).length;
+    if (length < min || length > max) {
+      problems.push(`description: ${length} code points (expected ${min}\u2013${max} for ${locale})`);
+    }
+    if (!endsAsSentence(description, locale)) {
+      problems.push("description: does not end with sentence punctuation");
+    }
+    const lower = description.toLowerCase();
+    const intro = PODCAST_INTROS.find((candidate) => lower.startsWith(candidate.toLowerCase()));
+    if (intro)
+      problems.push(`description: starts with the podcast intro ("${intro}")`);
+    if (description.includes("\u2026") || description.includes("...")) {
+      problems.push('description: contains "\u2026" or "..."');
+    }
+  }
+  const points = frontmatter.get("key_points");
+  if (!Array.isArray(points) || points.length === 0) {
+    problems.push("key_points: missing");
+  } else {
+    const labelMax = locale === "en" ? 28 : 14;
+    points.forEach((point, index) => {
+      const sep = point.indexOf(" \u2014 ");
+      if (sep < 0) {
+        problems.push(`key_points[${index}]: missing " \u2014 " separator`);
+        return;
+      }
+      const label = point.slice(0, sep);
+      const text = point.slice(sep + 3);
+      const labelLength = Array.from(label).length;
+      if (labelLength === 0 || labelLength > labelMax) {
+        problems.push(`key_points[${index}]: label "${label}" is ${labelLength} code points (max ${labelMax})`);
+      }
+      if (!endsAsSentence(text, locale)) {
+        problems.push(`key_points[${index}]: text does not end with sentence punctuation`);
+      }
+      if (point.includes("\u2026") || point.includes("...")) {
+        problems.push(`key_points[${index}]: contains "\u2026" or "..."`);
+      }
+    });
+  }
+  return problems;
+}
+
 // ../../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) {
@@ -12449,34 +12694,29 @@ function normalizeTag(raw) {
   }
   return slugify2(raw);
 }
-function mapContentToSurfingMarkdown(content, options = {}) {
-  let title = content.title;
-  if (!title) {
-    const match = content.body.match(/^#\s+(.+)$/m);
-    title = match?.[1] ? match[1].trim() : "Untitled Post";
-  }
-  let description;
-  if (typeof content.metadata?.description === "string") {
-    description = content.metadata.description;
-  } else {
-    const paragraphs = content.body.split(/\n\s*\n/).map((p) => p.replace(/^#+\s+.*$/, "").trim()).filter((p) => p.length > 0);
-    if (paragraphs.length > 0) {
-      description = paragraphs[0];
-    }
-  }
+function contentTags(content) {
   const rawTags = Array.isArray(content.metadata?.tags) ? [...content.metadata.tags] : Array.isArray(content.metadata?.keywords) ? [...content.metadata.keywords] : [];
   if (typeof content.metadata?.subCategory === "string" && content.metadata.subCategory.trim().length > 0) {
     const subRaw = content.metadata.subCategory.trim();
     rawTags.push(/^sub-category\s*:/i.test(subRaw) ? subRaw : `sub-category:${subRaw}`);
   }
-  const tags = [
+  return [
     ...new Set(rawTags.filter((t) => typeof t === "string" && t.trim().length > 0).map((t) => normalizeTag(t)))
   ].filter((tag) => tag.length > 0);
+}
+function mapContentToSurfingMarkdown(content, options = {}) {
+  let title = content.title;
+  if (!title) {
+    const match = content.body.match(/^#\s+(.+)$/m);
+    title = match?.[1] ? match[1].trim() : "Untitled Post";
+  }
+  const description = typeof content.metadata?.description === "string" && content.metadata.description.length > 0 ? content.metadata.description : "";
+  const tags = contentTags(content);
   const isoDate = options.publishDate ?? new Date().toISOString().slice(0, 10);
   const draft = typeof content.metadata?.published === "boolean" ? !content.metadata.published : false;
   const frontmatterObj = {
     title,
-    description: description ?? "",
+    description,
     tags,
     publishDate: isoDate,
     draft,
@@ -12489,9 +12729,21 @@ function mapContentToSurfingMarkdown(content, options = {}) {
 ${content.body.trim()}
 `;
 }
+function isDigestContent(content) {
+  return contentTags(content).some((tag) => tag.includes(DIGEST_TAG));
+}
 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 !== ".") {
@@ -12549,7 +12801,8 @@ async function spawnCli(cmd, cwd) {
   const proc = Bun.spawn(cmd, {
     cwd,
     stdout: "pipe",
-    stderr: "pipe"
+    stderr: "pipe",
+    env: process.env
   });
   const [exitCode, stdout, stderr] = await Promise.all([
     proc.exited,
@@ -12594,8 +12847,82 @@ function requireRefined(filePath) {
     return;
   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`;
 }
-async function pushPostGit(surfdashRoot, relPostDir, message) {
-  return commitPostPaths(surfdashRoot, [relPostDir], message);
+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;
+  if (process.env.SURFDASH_DIGEST_CHECK === "warn") {
+    for (const problem of problems)
+      echoError(`digest check (warn): ${problem}`);
+    return;
+  }
+  return `digest frontmatter check failed: ${problems.join("; ")}`;
+}
+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);
@@ -12711,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)}`);
     }
@@ -12770,6 +13109,12 @@ async function syncPost(options) {
     if (spawned.exitCode !== 0) {
       return fail(`publish-orchestrator sync failed (exit ${spawned.exitCode}): ${withEmdashTokenHint(cliErrorText(spawned))}`);
     }
+    const localeInPath = postPath.postPath.match(/[\\/]content[\\/]posts[\\/]articles[\\/](zh|en|ja)[\\/]/);
+    if (localeInPath) {
+      const digestProblem = digestCheckGate(postPath.postPath, localeInPath[1]);
+      if (digestProblem)
+        return fail(digestProblem);
+    }
     return ResultSchema.parse({
       ok: true,
       target: TARGET,
@@ -12823,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}`);
@@ -12849,85 +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 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 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 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) && !COVER_EXTS.has(extname(coverPath).toLowerCase())) {
-    return fail(`metadata.coverImage must be one of ${[...COVER_EXTS].join(", ")}`);
-  }
-  await createNodeFileSystem().ensureDir(postDir);
-  let imageFrontmatter;
-  if (typeof coverPath === "string" && existsSync2(coverPath)) {
-    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
-  });
+  if (typeof coverPath === "string" && !existsSync2(coverPath)) {
+    return { ok: false, result: failNotSent(`metadata.coverImage not found: ${coverPath}`) };
+  }
+  if (typeof coverPath === "string" && !COVER_EXTS.has(extname(coverPath).toLowerCase())) {
+    return {
+      ok: false,
+      result: failNotSent(`metadata.coverImage must be one of ${[...COVER_EXTS].join(", ")}`)
+    };
+  }
+  if (isDigestContent(payload.content) && typeof coverPath !== "string") {
+    return { ok: false, result: failNotSent("digest post has no cover image (metadata.coverImage)") };
+  }
   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 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";
@@ -12937,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":
@@ -12999,9 +13620,14 @@ if (import.meta.main) {
   process.exit(await main2());
 }
 export {
+  DIGEST_TAG,
   PostsurfingFileCliTransport,
   awaitArticleLive,
+  checkDigestFrontmatter,
   commitPostPaths,
+  contentTags,
+  digestCheckGate,
+  extractFailingPostHint,
   fastForwardToOrigin,
   getPublishTransport,
   main2 as main,
@@ -13012,6 +13638,8 @@ export {
   pushPostGit,
   readRefinedSnapshot,
   requireRefined,
+  runListenLinkBackfill,
+  runSiteGate,
   slugify2 as slugify,
   withEmdashTokenHint
 };