@gobing-ai/knowledge-kit 0.0.21 → 0.0.22

package/plugins/generations/voice-gen/dist/index.js

@@ -21781,6 +21781,22 @@ var ResultSchema = exports_external.object({
   error: exports_external.string().optional(),
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
+var TargetOutcomeSchema = exports_external.object({
+  target: exports_external.string(),
+  ok: exports_external.boolean(),
+  status: exports_external.enum(["published", "failed", "skipped"]),
+  url: exports_external.string().optional(),
+  id: exports_external.string().optional(),
+  error: exports_external.string().optional(),
+  durationMs: exports_external.number().optional(),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
+var AggregateResultSchema = exports_external.object({
+  ok: exports_external.boolean(),
+  summary: exports_external.object({ total: exports_external.number(), succeeded: exports_external.number(), failed: exports_external.number(), skipped: exports_external.number() }),
+  targets: exports_external.array(TargetOutcomeSchema),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
 var DocListSchema = exports_external.array(DocSchema);
 var omniVoiceGenContentSchema = ContentSchema.extend({
   format: exports_external.literal("audio"),
@@ -21809,14 +21825,15 @@ var PluginKindSchema = exports_external.enum(PLUGIN_KINDS);
 // ../../packages/kk-core/src/manifest.ts
 init_zod();
 var OperationIOSchema = exports_external.enum(["doc-list", "markdown"]);
-var PluginManifestSchema = exports_external.object({
+var PluginOperationSchema = exports_external.object({ input: OperationIOSchema, output: OperationIOSchema });
+var PluginManifestSchema = exports_external.looseObject({
   name: exports_external.string().min(1),
   kind: PluginKindSchema,
   entry: exports_external.string().min(1),
   version: exports_external.string().optional(),
   description: exports_external.string().optional(),
-  operations: exports_external.record(exports_external.string(), exports_external.object({ input: OperationIOSchema, output: OperationIOSchema })).optional()
-}).passthrough();
+  operations: exports_external.record(exports_external.string(), PluginOperationSchema).optional()
+});
 // ../../node_modules/.bun/@gobing-ai+ts-runtime@0.4.39/node_modules/@gobing-ai/ts-runtime/dist/index.js
 init_file_system_node();
 init_config();
@@ -22249,16 +22266,22 @@ async function auditVoiceSegments(script, segmentWavs, segmentMetadata, client)
 }
 
 // ../../plugins/generations/voice-gen/src/voicebox-client.ts
+function resolveVoiceboxTimeoutMs() {
+  const raw = process.env.VOICEBOX_TIMEOUT_MS;
+  const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 600000;
+}
 function createVoiceboxClient(options = {}) {
   const rawUrl = options.url || process.env.VOICEBOX_URL || "http://127.0.0.1:17493";
   const url2 = rawUrl.replace(/\/+$/, "");
   const customFetch = options.fetch ?? globalThis.fetch;
   const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const requestTimeoutMs = resolveVoiceboxTimeoutMs();
   return {
     url: url2,
     async health() {
       try {
-        const res = await customFetch(`${url2}/health`);
+        const res = await customFetch(`${url2}/health`, { signal: AbortSignal.timeout(requestTimeoutMs) });
         if (!res.ok) {
           throw new Error(`HTTP ${res.status} ${res.statusText}`);
         }
@@ -22270,7 +22293,7 @@ function createVoiceboxClient(options = {}) {
     async resolveProfile(nameOrId) {
       let res;
       try {
-        res = await customFetch(`${url2}/profiles`);
+        res = await customFetch(`${url2}/profiles`, { signal: AbortSignal.timeout(requestTimeoutMs) });
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
         throw new Error(`Voicebox /profiles request failed at ${url2}: ${reason}`);
@@ -22303,7 +22326,8 @@ function createVoiceboxClient(options = {}) {
           headers: {
             "Content-Type": "application/json"
           },
-          body: JSON.stringify(body)
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(requestTimeoutMs)
         });
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -22335,7 +22359,7 @@ function createVoiceboxClient(options = {}) {
       while (true) {
         let res;
         try {
-          res = await customFetch(`${url2}/history/${id}`);
+          res = await customFetch(`${url2}/history/${id}`, { signal: AbortSignal.timeout(requestTimeoutMs) });
         } catch (err) {
           const reason = err instanceof Error ? err.message : String(err);
           throw new Error(`Voicebox /history/${id} request failed at ${url2}: ${reason}`);
@@ -22369,7 +22393,7 @@ function createVoiceboxClient(options = {}) {
     async downloadAudio(id) {
       let res;
       try {
-        res = await customFetch(`${url2}/audio/${id}`);
+        res = await customFetch(`${url2}/audio/${id}`, { signal: AbortSignal.timeout(requestTimeoutMs) });
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
         throw new Error(`Voicebox /audio/${id} request failed at ${url2}: ${reason}`);
@@ -22394,7 +22418,8 @@ function createVoiceboxClient(options = {}) {
       try {
         res = await customFetch(`${url2}/transcribe`, {
           method: "POST",
-          body: formData
+          body: formData,
+          signal: AbortSignal.timeout(requestTimeoutMs)
         });
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -22423,7 +22448,7 @@ var POLL_MS = 500;
 var LOG_PATH = "/tmp/voicebox-server.log";
 async function probeVoiceboxHealth(url2, customFetch) {
   try {
-    return (await customFetch(`${url2}/health`)).ok;
+    return (await customFetch(`${url2}/health`, { signal: AbortSignal.timeout(resolveVoiceboxTimeoutMs()) })).ok;
   } catch {
     return false;
   }
@@ -23097,6 +23122,7 @@ export {
   validateVoiceScript,
   transcriptionFidelity,
   transcodeWavToMp3,
+  resolveVoiceboxTimeoutMs,
   resolveInstruct,
   resolveEffectsChain,
   processGeneratorIO,

package/plugins/generations/voice-gen/src/voicebox-client.ts

@@ -56,18 +56,30 @@ export interface VoiceboxClientOptions {
 /**
  * Creates a client for the Voicebox local REST API.
  */
+/**
+ * Per-request timeout (ms): `VOICEBOX_TIMEOUT_MS` when set to a positive number, else 600 000.
+ * Voice generation is slow, so the default is generous — but every call must be bounded, because
+ * Bun's `fetch` has no overall request deadline without a `signal` (R5).
+ */
+export function resolveVoiceboxTimeoutMs(): number {
+    const raw = process.env.VOICEBOX_TIMEOUT_MS;
+    const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 600_000;
+}
+
 export function createVoiceboxClient(options: VoiceboxClientOptions = {}): VoiceboxClient {
     const rawUrl = options.url || process.env.VOICEBOX_URL || 'http://127.0.0.1:17493';
     const url = rawUrl.replace(/\/+$/, '');
     const customFetch = options.fetch ?? globalThis.fetch;
     const sleep = options.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const requestTimeoutMs = resolveVoiceboxTimeoutMs();
 
     return {
         url,
 
         async health(): Promise<void> {
             try {
-                const res = await customFetch(`${url}/health`);
+                const res = await customFetch(`${url}/health`, { signal: AbortSignal.timeout(requestTimeoutMs) });
                 if (!res.ok) {
                     throw new Error(`HTTP ${res.status} ${res.statusText}`);
                 }
@@ -82,7 +94,7 @@ export function createVoiceboxClient(options: VoiceboxClientOptions = {}): Voice
         async resolveProfile(nameOrId: string): Promise<VoiceboxProfile> {
             let res: Response;
             try {
-                res = await customFetch(`${url}/profiles`);
+                res = await customFetch(`${url}/profiles`, { signal: AbortSignal.timeout(requestTimeoutMs) });
             } catch (err: unknown) {
                 const reason = err instanceof Error ? err.message : String(err);
                 throw new Error(`Voicebox /profiles request failed at ${url}: ${reason}`);
@@ -123,6 +135,7 @@ export function createVoiceboxClient(options: VoiceboxClientOptions = {}): Voice
                         'Content-Type': 'application/json',
                     },
                     body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(requestTimeoutMs),
                 });
             } catch (err: unknown) {
                 const reason = err instanceof Error ? err.message : String(err);
@@ -170,7 +183,7 @@ export function createVoiceboxClient(options: VoiceboxClientOptions = {}): Voice
             while (true) {
                 let res: Response;
                 try {
-                    res = await customFetch(`${url}/history/${id}`);
+                    res = await customFetch(`${url}/history/${id}`, { signal: AbortSignal.timeout(requestTimeoutMs) });
                 } catch (err: unknown) {
                     const reason = err instanceof Error ? err.message : String(err);
                     throw new Error(`Voicebox /history/${id} request failed at ${url}: ${reason}`);
@@ -212,7 +225,7 @@ export function createVoiceboxClient(options: VoiceboxClientOptions = {}): Voice
         async downloadAudio(id: string): Promise<Uint8Array> {
             let res: Response;
             try {
-                res = await customFetch(`${url}/audio/${id}`);
+                res = await customFetch(`${url}/audio/${id}`, { signal: AbortSignal.timeout(requestTimeoutMs) });
             } catch (err: unknown) {
                 const reason = err instanceof Error ? err.message : String(err);
                 throw new Error(`Voicebox /audio/${id} request failed at ${url}: ${reason}`);
@@ -242,6 +255,7 @@ export function createVoiceboxClient(options: VoiceboxClientOptions = {}): Voice
                 res = await customFetch(`${url}/transcribe`, {
                     method: 'POST',
                     body: formData,
+                    signal: AbortSignal.timeout(requestTimeoutMs),
                 });
             } catch (err: unknown) {
                 const reason = err instanceof Error ? err.message : String(err);

package/plugins/generations/voice-gen/src/voicebox-server.ts

@@ -3,6 +3,7 @@ import { existsSync, openSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { echoError } from '@gobing-ai/ts-utils';
+import { resolveVoiceboxTimeoutMs } from './voicebox-client';
 
 /** Boot wait / poll cadence for a freshly spawned local server (Voicebox cold start ≈ 2-5s). */
 const BOOT_WAIT_MS = 30_000;
@@ -23,7 +24,7 @@ export interface VoiceboxServerOptions {
 
 async function probeVoiceboxHealth(url: string, customFetch: typeof fetch): Promise<boolean> {
     try {
-        return (await customFetch(`${url}/health`)).ok;
+        return (await customFetch(`${url}/health`, { signal: AbortSignal.timeout(resolveVoiceboxTimeoutMs()) })).ok;
     } catch {
         return false;
     }

package/plugins/ingestions/aihot-ingest/dist/index.js

@@ -21781,6 +21781,22 @@ var ResultSchema = exports_external.object({
   error: exports_external.string().optional(),
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
+var TargetOutcomeSchema = exports_external.object({
+  target: exports_external.string(),
+  ok: exports_external.boolean(),
+  status: exports_external.enum(["published", "failed", "skipped"]),
+  url: exports_external.string().optional(),
+  id: exports_external.string().optional(),
+  error: exports_external.string().optional(),
+  durationMs: exports_external.number().optional(),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
+var AggregateResultSchema = exports_external.object({
+  ok: exports_external.boolean(),
+  summary: exports_external.object({ total: exports_external.number(), succeeded: exports_external.number(), failed: exports_external.number(), skipped: exports_external.number() }),
+  targets: exports_external.array(TargetOutcomeSchema),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
 var DocListSchema = exports_external.array(DocSchema);
 var omniVoiceGenContentSchema = ContentSchema.extend({
   format: exports_external.literal("audio"),
@@ -21809,14 +21825,15 @@ var PluginKindSchema = exports_external.enum(PLUGIN_KINDS);
 // ../../packages/kk-core/src/manifest.ts
 init_zod();
 var OperationIOSchema = exports_external.enum(["doc-list", "markdown"]);
-var PluginManifestSchema = exports_external.object({
+var PluginOperationSchema = exports_external.object({ input: OperationIOSchema, output: OperationIOSchema });
+var PluginManifestSchema = exports_external.looseObject({
   name: exports_external.string().min(1),
   kind: PluginKindSchema,
   entry: exports_external.string().min(1),
   version: exports_external.string().optional(),
   description: exports_external.string().optional(),
-  operations: exports_external.record(exports_external.string(), exports_external.object({ input: OperationIOSchema, output: OperationIOSchema })).optional()
-}).passthrough();
+  operations: exports_external.record(exports_external.string(), PluginOperationSchema).optional()
+});
 // ../../node_modules/.bun/@gobing-ai+ts-runtime@0.4.39/node_modules/@gobing-ai/ts-runtime/dist/index.js
 init_file_system_node();
 init_config();
@@ -21911,6 +21928,7 @@ init_zod();
 
 // ../../plugins/ingestions/aihot-ingest/src/client.ts
 init_zod();
+var REQUEST_TIMEOUT_MS = 120000;
 var AIHOT_BASE_URL = "https://aihot.virxact.com";
 var DEFAULT_AIHOT_USER_AGENT = "aihot-ingest/1.0.0";
 var AihotItemSchema = exports_external.object({
@@ -21996,7 +22014,8 @@ class AihotClient {
       headers: {
         Accept: "application/json",
         "User-Agent": this.userAgent
-      }
+      },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
     if (!res.ok) {
       const errBody = (await res.text()).slice(0, 1000);
@@ -22019,7 +22038,8 @@ class AihotClient {
       headers: {
         Accept: "application/json",
         "User-Agent": this.userAgent
-      }
+      },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
     if (!res.ok) {
       const errBody = (await res.text()).slice(0, 1000);

package/plugins/ingestions/aihot-ingest/src/client.ts

@@ -1,6 +1,9 @@
 import { echoError } from '@gobing-ai/ts-utils';
 import { z } from 'zod';
 
+/** Per-request timeout (ms) for aihot HTTP calls — Bun's `fetch` has no default deadline (R5). */
+const REQUEST_TIMEOUT_MS = 120_000;
+
 export const AIHOT_BASE_URL = 'https://aihot.virxact.com';
 export const DEFAULT_AIHOT_USER_AGENT = 'aihot-ingest/1.0.0';
 
@@ -123,6 +126,7 @@ export class AihotClient {
                 Accept: 'application/json',
                 'User-Agent': this.userAgent,
             },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         });
 
         if (!res.ok) {
@@ -152,6 +156,7 @@ export class AihotClient {
                 Accept: 'application/json',
                 'User-Agent': this.userAgent,
             },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         });
 
         if (!res.ok) {

package/plugins/ingestions/horizon-ingest/dist/index.js

@@ -21782,6 +21782,22 @@ var ResultSchema = exports_external.object({
   error: exports_external.string().optional(),
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
+var TargetOutcomeSchema = exports_external.object({
+  target: exports_external.string(),
+  ok: exports_external.boolean(),
+  status: exports_external.enum(["published", "failed", "skipped"]),
+  url: exports_external.string().optional(),
+  id: exports_external.string().optional(),
+  error: exports_external.string().optional(),
+  durationMs: exports_external.number().optional(),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
+var AggregateResultSchema = exports_external.object({
+  ok: exports_external.boolean(),
+  summary: exports_external.object({ total: exports_external.number(), succeeded: exports_external.number(), failed: exports_external.number(), skipped: exports_external.number() }),
+  targets: exports_external.array(TargetOutcomeSchema),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
 var DocListSchema = exports_external.array(DocSchema);
 var omniVoiceGenContentSchema = ContentSchema.extend({
   format: exports_external.literal("audio"),
@@ -21810,14 +21826,15 @@ var PluginKindSchema = exports_external.enum(PLUGIN_KINDS);
 // ../../packages/kk-core/src/manifest.ts
 init_zod();
 var OperationIOSchema = exports_external.enum(["doc-list", "markdown"]);
-var PluginManifestSchema = exports_external.object({
+var PluginOperationSchema = exports_external.object({ input: OperationIOSchema, output: OperationIOSchema });
+var PluginManifestSchema = exports_external.looseObject({
   name: exports_external.string().min(1),
   kind: PluginKindSchema,
   entry: exports_external.string().min(1),
   version: exports_external.string().optional(),
   description: exports_external.string().optional(),
-  operations: exports_external.record(exports_external.string(), exports_external.object({ input: OperationIOSchema, output: OperationIOSchema })).optional()
-}).passthrough();
+  operations: exports_external.record(exports_external.string(), PluginOperationSchema).optional()
+});
 // ../../node_modules/.bun/@gobing-ai+ts-runtime@0.4.39/node_modules/@gobing-ai/ts-runtime/dist/index.js
 init_file_system_node();
 init_config();

package/plugins/ingestions/last30days-ingest/dist/index.js

@@ -21783,6 +21783,22 @@ var ResultSchema = exports_external.object({
   error: exports_external.string().optional(),
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
+var TargetOutcomeSchema = exports_external.object({
+  target: exports_external.string(),
+  ok: exports_external.boolean(),
+  status: exports_external.enum(["published", "failed", "skipped"]),
+  url: exports_external.string().optional(),
+  id: exports_external.string().optional(),
+  error: exports_external.string().optional(),
+  durationMs: exports_external.number().optional(),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
+var AggregateResultSchema = exports_external.object({
+  ok: exports_external.boolean(),
+  summary: exports_external.object({ total: exports_external.number(), succeeded: exports_external.number(), failed: exports_external.number(), skipped: exports_external.number() }),
+  targets: exports_external.array(TargetOutcomeSchema),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
 var DocListSchema = exports_external.array(DocSchema);
 var omniVoiceGenContentSchema = ContentSchema.extend({
   format: exports_external.literal("audio"),
@@ -21811,14 +21827,15 @@ var PluginKindSchema = exports_external.enum(PLUGIN_KINDS);
 // ../../packages/kk-core/src/manifest.ts
 init_zod();
 var OperationIOSchema = exports_external.enum(["doc-list", "markdown"]);
-var PluginManifestSchema = exports_external.object({
+var PluginOperationSchema = exports_external.object({ input: OperationIOSchema, output: OperationIOSchema });
+var PluginManifestSchema = exports_external.looseObject({
   name: exports_external.string().min(1),
   kind: PluginKindSchema,
   entry: exports_external.string().min(1),
   version: exports_external.string().optional(),
   description: exports_external.string().optional(),
-  operations: exports_external.record(exports_external.string(), exports_external.object({ input: OperationIOSchema, output: OperationIOSchema })).optional()
-}).passthrough();
+  operations: exports_external.record(exports_external.string(), PluginOperationSchema).optional()
+});
 // ../../node_modules/.bun/@gobing-ai+ts-runtime@0.4.39/node_modules/@gobing-ai/ts-runtime/dist/index.js
 init_file_system_node();
 init_config();

package/plugins/ingestions/web-search/dist/index.js

@@ -21782,6 +21782,22 @@ var ResultSchema = exports_external.object({
   error: exports_external.string().optional(),
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
+var TargetOutcomeSchema = exports_external.object({
+  target: exports_external.string(),
+  ok: exports_external.boolean(),
+  status: exports_external.enum(["published", "failed", "skipped"]),
+  url: exports_external.string().optional(),
+  id: exports_external.string().optional(),
+  error: exports_external.string().optional(),
+  durationMs: exports_external.number().optional(),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
+var AggregateResultSchema = exports_external.object({
+  ok: exports_external.boolean(),
+  summary: exports_external.object({ total: exports_external.number(), succeeded: exports_external.number(), failed: exports_external.number(), skipped: exports_external.number() }),
+  targets: exports_external.array(TargetOutcomeSchema),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
 var DocListSchema = exports_external.array(DocSchema);
 var omniVoiceGenContentSchema = ContentSchema.extend({
   format: exports_external.literal("audio"),
@@ -21810,14 +21826,15 @@ var PluginKindSchema = exports_external.enum(PLUGIN_KINDS);
 // ../../packages/kk-core/src/manifest.ts
 init_zod();
 var OperationIOSchema = exports_external.enum(["doc-list", "markdown"]);
-var PluginManifestSchema = exports_external.object({
+var PluginOperationSchema = exports_external.object({ input: OperationIOSchema, output: OperationIOSchema });
+var PluginManifestSchema = exports_external.looseObject({
   name: exports_external.string().min(1),
   kind: PluginKindSchema,
   entry: exports_external.string().min(1),
   version: exports_external.string().optional(),
   description: exports_external.string().optional(),
-  operations: exports_external.record(exports_external.string(), exports_external.object({ input: OperationIOSchema, output: OperationIOSchema })).optional()
-}).passthrough();
+  operations: exports_external.record(exports_external.string(), PluginOperationSchema).optional()
+});
 // ../../node_modules/.bun/@gobing-ai+ts-runtime@0.4.39/node_modules/@gobing-ai/ts-runtime/dist/index.js
 init_file_system_node();
 init_config();
@@ -24042,6 +24059,7 @@ async function initializeLogger(options = {}) {
 }
 // ../../plugins/ingestions/web-search/src/index.ts
 var log = getLogger2("kk.ingestion.web-search");
+var REQUEST_TIMEOUT_MS = 120000;
 var FIXTURE_ENTRIES = [
   {
     sourceUri: "https://example.org/research/storm-overview",
@@ -24101,6 +24119,7 @@ async function searchFirecrawl(input, deps) {
         "Content-Type": "application/json",
         Authorization: `Bearer ${key}`
       },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
       body: JSON.stringify({
         query: input.topic,
         limit: input.maxResults,

package/plugins/ingestions/web-search/src/index.ts

@@ -8,6 +8,9 @@ import { echoError } from '@gobing-ai/ts-utils';
 
 const log = getLogger('kk.ingestion.web-search');
 
+/** Per-request timeout (ms) for the Firecrawl call — Bun's `fetch` has no default deadline (R5). */
+const REQUEST_TIMEOUT_MS = 120_000;
+
 /** Validated `--in` input per the 0054 contract (`topic` required; `maxResults`/`fixture` optional). */
 interface InInput {
     topic: string;
@@ -136,6 +139,7 @@ export async function searchFirecrawl(input: InInput, deps: SearchDeps): Promise
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${key}`,
             },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             body: JSON.stringify({
                 query: input.topic,
                 limit: input.maxResults,

package/plugins/kk/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "kk",
-    "version": "0.0.21",
+    "version": "0.0.22",
     "description": "knowledge-kit Claude Code plugin: skills, commands, subagents, hooks, and rules"
 }

package/plugins/kk/scripts/kk-workflow-stages.ts

@@ -54,7 +54,7 @@ import {
     writeFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 
 const SCRIPTS_DIR = import.meta.dir;
 const VALIDATE_SIDECAR = 'validate-voicescript.ts';
@@ -1336,6 +1336,17 @@ function dailyPatchSurfdash(args: string[]): void {
         const postPath = (sd.metadata as Record<string, unknown> | undefined)?.postPath;
         if (typeof postPath !== 'string' || postPath === '')
             failWith(1, 'patch-surfdash: surfdash result carries no postPath');
+        // Refuse before anything is written: surfdash's deploy.yml publishes from main, so a commit
+        // on any other branch is invisible to production. Placed here (after the input checks) so a
+        // refusal leaves the working tree untouched.
+        const head = spawnSync('git', ['-C', surfdashRoot, 'rev-parse', '--abbrev-ref', 'HEAD'])
+            .stdout?.toString()
+            .trim();
+        if (head !== 'main')
+            failWith(1, `patch-surfdash: refusing to commit on '${head}' — surfdash deploys from main`);
+        // Paths this run actually wrote, relative to surfdashRoot. `git add`/`commit` take these as a
+        // pathspec so the operator's unrelated staged work is never swept into the commit.
+        const written: string[] = [];
         const slugDir = dirname(postPath);
         const showNotesUrl = typeof pod.url === 'string' ? pod.url : '';
         const coverUrl = ((pod.metadata as Record<string, unknown> | undefined)?.imageUrl as string | undefined) ?? '';
@@ -1366,10 +1377,19 @@ function dailyPatchSurfdash(args: string[]): void {
             // Upsert a single-line `key: 'value'`; the regex consumes folded-scalar continuation
             // lines (`og_image: >-\n  https://...`) so multi-line publish output is replaced whole.
             const upsertKey = (src: string, key: string, value: string): string => {
-                const line = `${key}: '${value}'`;
+                // YAML single-quoted scalars escape `'` as `''`; the replacement is a function so
+                // `$&`/`$1`/`$$` in the value are never expanded. Scope the match to the frontmatter
+                // (recomputed per call, since each upsert shifts offsets) so a body line starting with
+                // `image:` is not rewritten.
+                const end = src.indexOf('\n---', 3);
+                const fm = src.slice(0, end);
+                const body = src.slice(end);
+                const line = `${key}: '${value.replaceAll("'", "''")}'`;
                 const re = new RegExp(`^${key}:.*(?:\\n[ \\t]+.*)*`, 'm');
-                if (re.test(src)) return src.replace(re, line);
-                return src.replace(/^publishDate: .*$/m, (m0) => `${m0}\n${line}`);
+                const next = re.test(fm)
+                    ? fm.replace(re, () => line)
+                    : fm.replace(/^publishDate: .*$/m, (m0) => `${m0}\n${line}`);
+                return next + body;
             };
             if (coverUrl !== '') {
                 // 20260919 prod feedback: the podcast-hosted cover URL wins even when surfdash-pub
@@ -1383,6 +1403,7 @@ function dailyPatchSurfdash(args: string[]): void {
                     const assets = join(dir, 'assets');
                     mkdirSync(assets, { recursive: true });
                     copyFileSync(localCover, join(assets, 'cover.png'));
+                    written.push(relative(surfdashRoot, join(assets, 'cover.png')));
                     md = upsertKey(md, 'image', './assets/cover.png');
                     md = upsertKey(md, 'og_image', './assets/cover.png');
                 }
@@ -1392,6 +1413,7 @@ function dailyPatchSurfdash(args: string[]): void {
             }
             if (md !== readFileSync(indexMd, 'utf-8')) {
                 sted('write', indexMd, () => writeFileSync(indexMd, md));
+                written.push(relative(surfdashRoot, indexMd));
                 changed++;
             }
         }
@@ -1403,9 +1425,15 @@ function dailyPatchSurfdash(args: string[]): void {
             const r = spawnSync('git', ['-C', surfdashRoot, ...a]);
             if (r.status !== 0) failWith(1, `patch-surfdash: git ${a[0]} failed: ${r.stderr?.toString().trim()}`);
         };
-        git('add', 'content/posts/articles');
-        git('commit', '-m', `feat: cover + podcast cross-link for ${basename(slugDir)} (kk daily patch)`);
-        if (process.env.SURFDASH_AUTO_PUSH !== '0') git('push');
+        git('add', '--', ...written);
+        git(
+            'commit',
+            '-m',
+            `feat: cover + podcast cross-link for ${basename(slugDir)} (kk daily patch)`,
+            '--',
+            ...written,
+        );
+        if (process.env.SURFDASH_AUTO_PUSH !== '0') git('push', 'origin', 'main');
         console.log(
             `patch-surfdash: patched ${changed} post(s), committed${process.env.SURFDASH_AUTO_PUSH !== '0' ? ' + pushed' : ' (push skipped: SURFDASH_AUTO_PUSH=0)'}`,
         );

package/plugins/kk/scripts/render-md.ts

@@ -101,6 +101,12 @@ function renderReferences(references: ContentInput['references']): string {
     return `\n\n## References\n\n${lines.join('\n')}`;
 }
 
+/** Escape `\\`, `[`, `]` so link text cannot terminate the `[title]` form early (0155 R4). */
+const escapeLinkText = (s: string): string => s.replace(/[\\[\]]/g, '\\$&');
+/** Percent-encode characters that would break the inline link destination `(url)` (0155 R4). */
+const escapeLinkUrl = (s: string): string =>
+    s.replace(/[ ()<>]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`);
+
 function renderReferenceLabel(ref: Ref): string {
     const { url, title, cite } = ref;
     const titleT = title?.trim() ?? '';
@@ -108,7 +114,7 @@ function renderReferenceLabel(ref: Ref): string {
     const citeT = cite?.trim() ?? '';
     let label: string;
     if (titleT !== '' && urlT !== '') {
-        label = `[${titleT}](${urlT})`;
+        label = `[${escapeLinkText(titleT)}](${escapeLinkUrl(urlT)})`;
     } else if (titleT !== '') {
         label = titleT;
     } else if (urlT !== '') {