@gobing-ai/knowledge-kit 0.0.34 → 0.0.36

package/plugins/publishings/surfdash-pub/package.json

@@ -12,6 +12,6 @@
         "@gobing-ai/ts-utils": "catalog:"
     },
     "devDependencies": {
-        "@types/bun": "1.3.14"
+        "@types/bun": "1.4.3"
     }
 }

package/plugins/publishings/surfdash-pub/src/index.ts

@@ -1,17 +1,18 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { copyFile, cp, writeFile } from 'node:fs/promises';
-import { dirname, extname, isAbsolute, join, resolve, sep } from 'node:path';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 import { type Content, ContentSchema, type Result, ResultSchema } from '@gobing-ai/kk-core';
 import type { PublishTransport, PublishTransportPayload } from '@gobing-ai/publish-harness';
 import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import { echoError } from '@gobing-ai/ts-utils';
+import { type PatchPostOutcome, patchPostFiles } from './patch';
 
 /** Result target name for this plugin. */
 const TARGET = 'surfdash';
 
 /** Management operations routed via `options.operation` (L1 R7; pattern from podcast-pub). */
-const OPERATIONS = ['publish', 'scaffold-locale', 'sync'] as const;
+const OPERATIONS = ['publish', 'scaffold-locale', 'sync', 'patch'] as const;
 type Operation = (typeof OPERATIONS)[number];
 
 /** Locales `scaffold-locale` can scaffold; LLM translation stays in the workflow's agent step. */
@@ -24,10 +25,18 @@ const COVER_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
 /** Target-specific options carried on the invoke payload's `options` channel. */
 interface SurfdashPubOptions {
     operation?: unknown;
-    /** zh `index.md` absolute path inside the surfdash tree; required for `scaffold-locale` and `sync`. */
+    /** zh `index.md` absolute path inside the surfdash tree; required for `scaffold-locale`, `sync` and `patch`. */
     postPath?: unknown;
     /** Draft locale to scaffold; required for `scaffold-locale`. */
     target?: unknown;
+    /** `patch`: podcast-hosted cover URL for `image`/`og_image` (empty → the local cover fallback). */
+    coverUrl?: unknown;
+    /** `patch`: podcast episode URL appended as the cross-link (empty → none). */
+    showNotesUrl?: unknown;
+    /** `patch`: this run's rendered cover, used when `coverUrl` is empty. */
+    localCover?: unknown;
+    /** `patch`: `YYYY-MM-DD` episode date for the cross-link text. */
+    dateIso?: unknown;
 }
 
 /**
@@ -81,9 +90,16 @@ export function mapContentToSurfingMarkdown(content: Content, options: MapConten
         : Array.isArray(content.metadata?.keywords)
           ? content.metadata.keywords
           : [];
-    const tags = rawTags
-        .filter((t): t is string => typeof t === 'string' && t.trim().length > 0)
-        .map((t: string) => slugify(t));
+    // `slugify` drops non-ASCII, so a Chinese tag (`硬件发布`) collapsed to '' and shipped as an empty
+    // YAML tag — the site renders it as a blank chip (seen on 20261011-ai-2026-10-11). Case variants
+    // also collapsed to the same slug twice (`AI` + `ai`), so the set dedupes.
+    const tags = [
+        ...new Set(
+            rawTags
+                .filter((t): t is string => typeof t === 'string' && t.trim().length > 0)
+                .map((t: string) => slugify(t)),
+        ),
+    ].filter((tag) => tag.length > 0);
 
     const isoDate = options.publishDate ?? new Date().toISOString().slice(0, 10);
     const firstRefUrl = content.references?.[0]?.url;
@@ -250,6 +266,10 @@ export type GitPushOutcome = { ok: true; hash: string } | { ok: false; error: st
  * out of the publish commit. Fails loud on branch/commit/push errors.
  */
 export async function pushPostGit(surfdashRoot: string, relPostDir: string, message: string): Promise<GitPushOutcome> {
+    return commitPostPaths(surfdashRoot, [relPostDir], message);
+}
+/** Refuse a checkout that cannot deploy before anything is written (`deploy.yml` builds `main` only). */
+async function assertMainBranch(surfdashRoot: string): Promise<{ ok: true } | { ok: false; error: string }> {
     const branch = await spawnCli(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], surfdashRoot);
     if (branch.exitCode !== 0) return { ok: false, error: `surfdash git branch check failed: ${cliErrorText(branch)}` };
     const branchName = branch.stdout.trim();
@@ -259,14 +279,34 @@ export async function pushPostGit(surfdashRoot: string, relPostDir: string, mess
             error: `surfdash checkout is on '${branchName}', not 'main' — deploy.yml only builds main; refusing to push from a feature branch`,
         };
     }
-    const add = await spawnCli(['git', 'add', '--', relPostDir], surfdashRoot);
+    return { ok: true };
+}
+
+/**
+ * Commits several paths of the surfdash checkout and pushes them to `main` — the plural form of
+ * {@link pushPostGit} the post-patch needs (it writes the posts and any copied cover). Same
+ * pathspec-scoped commit, so unrelated staged work is never swept in, and the same idempotent retry:
+ * content identical to HEAD stages nothing and only pushes when `origin/main` lacks the paths.
+ */
+export async function commitPostPaths(
+    surfdashRoot: string,
+    relPaths: string[],
+    message: string,
+    push = true,
+): Promise<GitPushOutcome> {
+    if (relPaths.length === 0) return { ok: true, hash: 'unchanged' };
+    const branch = await assertMainBranch(surfdashRoot);
+    if (!branch.ok) return branch;
+    const add = await spawnCli(['git', 'add', '--', ...relPaths], surfdashRoot);
     if (add.exitCode !== 0) return { ok: false, error: `surfdash git add failed: ${cliErrorText(add)}` };
-    // Idempotent retry: post content identical to HEAD stages nothing. Only push when
-    // origin lacks commits touching this post; a clean post means it's already live.
-    const staged = await spawnCli(['git', 'diff', '--cached', '--quiet', '--', relPostDir], surfdashRoot);
+    const staged = await spawnCli(['git', 'diff', '--cached', '--quiet', '--', ...relPaths], surfdashRoot);
     if (staged.exitCode === 0) {
+        if (!push) {
+            const hash = await spawnCli(['git', 'rev-parse', '--short', 'HEAD'], surfdashRoot);
+            return { ok: true, hash: hash.stdout.trim() || 'unknown' };
+        }
         const unpushed = await spawnCli(
-            ['git', 'diff', '--quiet', 'origin/main..HEAD', '--', relPostDir],
+            ['git', 'diff', '--quiet', 'origin/main..HEAD', '--', ...relPaths],
             surfdashRoot,
         );
         if (unpushed.exitCode === 0) {
@@ -274,14 +314,18 @@ export async function pushPostGit(surfdashRoot: string, relPostDir: string, mess
             return { ok: true, hash: hash.stdout.trim() || 'unknown' };
         }
     } else {
-        const commit = await spawnCli(['git', 'commit', '-m', message, '--', relPostDir], surfdashRoot);
+        const commit = await spawnCli(['git', 'commit', '-m', message, '--', ...relPaths], surfdashRoot);
         if (commit.exitCode !== 0) return { ok: false, error: `surfdash git commit failed: ${cliErrorText(commit)}` };
     }
-    const push = await spawnCli(['git', 'push', 'origin', 'main'], surfdashRoot);
-    if (push.exitCode !== 0) {
+    if (!push) {
+        const hash = await spawnCli(['git', 'rev-parse', '--short', 'HEAD'], surfdashRoot);
+        return { ok: true, hash: hash.stdout.trim() || 'unknown' };
+    }
+    const pushed = await spawnCli(['git', 'push', 'origin', 'main'], surfdashRoot);
+    if (pushed.exitCode !== 0) {
         return {
             ok: false,
-            error: `surfdash git push failed (deploy.yml deploys on push to main): ${cliErrorText(push)}`,
+            error: `surfdash git push failed (deploy.yml deploys on push to main): ${cliErrorText(pushed)}`,
         };
     }
     const hash = await spawnCli(['git', 'rev-parse', '--short', 'HEAD'], surfdashRoot);
@@ -433,6 +477,82 @@ async function syncPost(options: SurfdashPubOptions): Promise<Result> {
     }
 }
 
+/** `options.<key>` when it is a string, trimmed; else ''. `patch`'s four optional fields read this way. */
+function strOption(options: SurfdashPubOptions, key: 'coverUrl' | 'showNotesUrl' | 'localCover' | 'dateIso'): string {
+    const raw = options[key];
+    return typeof raw === 'string' ? raw.trim() : '';
+}
+
+/**
+ * `patch` — post-publish healing for one published episode (2026-10-12; moved here from the kk stage
+ * `daily-patch-surfdash`, which owned the publisher's work): the podcast-hosted cover URL in
+ * `image`/`og_image`, the per-locale podcast cross-link, the local cover's `assets/` fallback, the
+ * EmDash re-sync that makes CMS cards carry a servable image, then a pathspec commit + push.
+ *
+ * Ordering is load-bearing: the branch guard runs before anything is written (a checkout that cannot
+ * deploy must not be patched, and the failure leaves the tree untouched), and the re-sync runs even
+ * when no file changed, so a re-run heals rows an earlier run left stale.
+ */
+async function patchPost(options: SurfdashPubOptions): Promise<Result> {
+    const postPath = resolvePostPath(options);
+    if ('error' in postPath) return fail(postPath.error);
+    const surfdashRoot = resolveSurfdashRoot();
+    if (!surfdashRoot) {
+        return fail('SURFDASH_ROOT is required when POSTSURFING_BIN is not a path inside the surfdash checkout');
+    }
+    const outsideRoot = postPathOutsideRoot(postPath.postPath, surfdashRoot);
+    if (outsideRoot) return fail(outsideRoot);
+    const branch = await assertMainBranch(surfdashRoot);
+    if (!branch.ok) return fail(branch.error);
+
+    let outcome: PatchPostOutcome;
+    try {
+        outcome = await patchPostFiles({
+            postPath: postPath.postPath,
+            coverUrl: strOption(options, 'coverUrl'),
+            showNotesUrl: strOption(options, 'showNotesUrl'),
+            localCover: strOption(options, 'localCover'),
+            dateIso: strOption(options, 'dateIso'),
+        });
+    } catch (error: unknown) {
+        return fail(`patch error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (outcome.changed === 0) echoError(`patch: no post bytes changed for ${outcome.slug}`);
+    const synced = await syncPost({ postPath: postPath.postPath });
+    const commit = await commitPostPaths(
+        surfdashRoot,
+        outcome.written.map((path) => relative(surfdashRoot, path)),
+        `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}`);
+    const metadata = {
+        postPath: postPath.postPath,
+        changed: outcome.changed,
+        locales: Object.keys(outcome.images),
+        absentLocales: outcome.absent,
+        cmsResync: synced.ok ? 'ok' : 'failed',
+        gitCommit: commit.hash,
+    };
+    if (!synced.ok) {
+        // The posts are patched and committed; only the CMS rows keep the unservable cover. Reported
+        // as a failure so the completeness report says `cms-resync=failed`, with `metadata.cmsResync`
+        // letting the caller treat it as the soft channel it is.
+        return ResultSchema.parse({
+            ok: false,
+            target: TARGET,
+            error: `cms re-sync failed: ${synced.error ?? 'ok=false'}`,
+            metadata,
+        });
+    }
+    return ResultSchema.parse({
+        ok: true,
+        target: TARGET,
+        message: `patched ${outcome.changed} post(s) for ${outcome.slug}`,
+        metadata,
+    });
+}
+
 /**
  * Publish path (behavior unchanged since E3): maps Content into surfdash markdown under
  * `content/posts/<collection>/<locale>/<slug>/index.md` and invokes the postsurfing CLI.
@@ -565,6 +685,8 @@ export class PostsurfingFileCliTransport implements PublishTransport {
                 return scaffoldLocale(options);
             case 'sync':
                 return syncPost(options);
+            case 'patch':
+                return patchPost(options);
             case 'publish':
                 return publishPost(payload);
         }

package/plugins/publishings/surfdash-pub/src/patch.ts

@@ -0,0 +1,144 @@
+/**
+ * Post-publish patching for a published daily episode (2026-10-12).
+ *
+ * Moved here from the kk stage `daily-patch-surfdash`, which owned the publisher's work: the
+ * podcast-hosted cover URL in `image`/`og_image`, the per-locale podcast cross-link, the local
+ * cover's `assets/` fallback, and the EmDash re-sync that makes CMS cards carry a servable image
+ * (the pre-patch `./assets/cover.png` returns 404 from the deployed worker — prod feedback
+ * 2026-09-29 / 2026-10-02 / 2026-10-11). Living in the publisher means every path that publishes a
+ * post can heal it: the voice1 workflow, the voice2 DAG and a hand run call one operation.
+ *
+ * This module owns only the file work (deterministic, no network); the caller (`./index`) owns the
+ * branch guard, the CMS re-sync and the git commit, in that order.
+ */
+import { basename, dirname, join, sep } from 'node:path';
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
+
+/** The locales a daily post carries; zh is the primary whose directory anchors the other two. */
+export const PATCH_LOCALES = ['zh', 'en', 'ja'] as const;
+export type PatchLocale = (typeof PATCH_LOCALES)[number];
+
+/** Everything {@link patchPostFiles} needs; all paths absolute. */
+export interface PatchPostRequest {
+    /** Absolute `<root>/content/posts/articles/zh/<slug>/index.md` — the primary post. */
+    postPath: string;
+    /** Podcast-hosted cover URL; empty → the local cover is copied into `assets/` instead. */
+    coverUrl: string;
+    /** Podcast episode URL for the cross-link line; empty → no cross-link. */
+    showNotesUrl: string;
+    /** This run's rendered cover, the fallback when `coverUrl` is empty. */
+    localCover: string;
+    /** `YYYY-MM-DD` episode date used in the cross-link text. */
+    dateIso: string;
+}
+
+/** What the file pass changed; the caller commits exactly {@link PatchPostOutcome.written}. */
+export interface PatchPostOutcome {
+    /** Absolute paths written (posts plus any copied cover). */
+    written: string[];
+    /** Files whose bytes changed (not the copied cover). */
+    changed: number;
+    /** Locales with no published post on disk, in request order. */
+    absent: PatchLocale[];
+    /** Locale → the frontmatter image value the patch settled on. */
+    images: Record<string, string>;
+    /** The primary post's directory name, for the commit message. */
+    slug: string;
+}
+
+/**
+ * `…/articles/zh/<slug>/index.md` → the sibling locale's `index.md`, with the LAST `/zh/` segment
+ * swapped. Undefined when the path carries no `/zh/` segment, which the caller reports as absent.
+ */
+export function localeIndexPath(postPath: string, locale: PatchLocale): string | undefined {
+    if (locale === 'zh') return postPath;
+    const marker = `${sep}zh${sep}`;
+    const idx = postPath.lastIndexOf(marker);
+    if (idx < 0) return undefined;
+    return `${postPath.slice(0, idx)}${sep}${locale}${sep}${postPath.slice(idx + marker.length)}`;
+}
+
+/**
+ * The podcast cross-link line per locale (task 0189 R4: the column's episode-title pattern, not the
+ * retired news-bulletin name).
+ */
+export function crossLinkFor(locale: PatchLocale, dateIso: string, showNotesUrl: string): string {
+    const links: Record<PatchLocale, string> = {
+        zh: `🎧 本期已同步制作为播客节目，[点击收听《每日AI乱炖 · ${dateIso}》](${showNotesUrl})。`,
+        en: `🎧 This episode is also available as a podcast: [listen to 每日AI乱炖 · ${dateIso}](${showNotesUrl}).`,
+        ja: `🎧 本エピソードはポッドキャストでも配信中：[每日AI乱炖 · ${dateIso} を聴く](${showNotesUrl})。`,
+    };
+    return links[locale];
+}
+
+/** The closing `---` of a document's frontmatter, or -1 when there is none. */
+function frontmatterEnd(markdown: string): number {
+    return markdown.indexOf('\n---', 3);
+}
+
+/**
+ * Upsert one single-line `key: 'value'` in a document's frontmatter.
+ *
+ * The regex consumes folded-scalar continuation lines (`og_image: >-\n  https://…`) so multi-line
+ * publish output is replaced whole, and the replacement is a function so `$&`/`$1` in the value are
+ * never expanded. Scoped to the frontmatter, so a body line starting with `image:` is never
+ * rewritten. A key that is absent is inserted after `publishDate`.
+ */
+export function upsertFrontmatterKey(markdown: string, key: string, value: string): string {
+    const end = frontmatterEnd(markdown);
+    if (end < 0) return markdown;
+    const fm = markdown.slice(0, end);
+    const body = markdown.slice(end);
+    const line = `${key}: '${value.replaceAll("'", "''")}'`;
+    const re = new RegExp(`^${key}:.*(?:\\n[ \\t]+.*)*`, 'm');
+    const next = re.test(fm) ? fm.replace(re, () => line) : fm.replace(/^publishDate: .*$/m, (m0) => `${m0}\n${line}`);
+    return next + body;
+}
+
+/**
+ * Patch the published posts of one episode: cover URL (or the local cover's `assets/` fallback),
+ * then the podcast cross-link. Idempotent per file — a post that already carries the values keeps
+ * its bytes and is not committed.
+ */
+export async function patchPostFiles(request: PatchPostRequest): Promise<PatchPostOutcome> {
+    const fs = createNodeFileSystem();
+    const written: string[] = [];
+    const absent: PatchLocale[] = [];
+    const images: Record<string, string> = {};
+    let changed = 0;
+    for (const locale of PATCH_LOCALES) {
+        const indexMd = localeIndexPath(request.postPath, locale);
+        if (indexMd === undefined || !(await fs.exists(indexMd))) {
+            absent.push(locale);
+            continue;
+        }
+        const dir = dirname(indexMd);
+        const before = await fs.readFile(indexMd);
+        let md = before;
+        const end = frontmatterEnd(md);
+        const fm = end < 0 ? md : md.slice(0, end);
+        if (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))) {
+            // Fallback for a run without a podcast cover: ship the rendered cover with the post.
+            const asset = join(dir, 'assets', 'cover.png');
+            await fs.ensureDir(dirname(asset));
+            await fs.copy(request.localCover, asset);
+            written.push(asset);
+            md = upsertFrontmatterKey(md, 'image', './assets/cover.png');
+            md = upsertFrontmatterKey(md, 'og_image', './assets/cover.png');
+            images[locale] = './assets/cover.png';
+        }
+        if (request.showNotesUrl !== '' && !md.includes(request.showNotesUrl)) {
+            md = `${md.replace(/\s*$/, '')}\n\n${crossLinkFor(locale, request.dateIso, request.showNotesUrl)}\n`;
+        }
+        if (md !== before) {
+            await fs.writeFile(indexMd, md);
+            written.push(indexMd);
+            changed += 1;
+        }
+    }
+    return { written, changed, absent, images, slug: basename(dirname(request.postPath)) };
+}