@gobing-ai/knowledge-kit 0.0.11 → 0.0.13

package/dist/index.js

@@ -26016,7 +26016,8 @@ function useColor() {
 var program = new Command;
 
 // src/fanin.ts
-import { resolve as resolve2 } from "path";
+import { tmpdir } from "os";
+import { isAbsolute as isAbsolute2, join as join3, resolve as resolve3 } from "path";
 
 // ../../packages/kk-core/src/kinds.ts
 init_zod();
@@ -26093,12 +26094,14 @@ function isPluginKind(value) {
 }
 // ../../packages/kk-core/src/manifest.ts
 init_zod();
+var OperationIOSchema = exports_external.enum(["doc-list", "markdown"]);
 var PluginManifestSchema = exports_external.object({
   name: exports_external.string().min(1),
   kind: PluginKindSchema,
   entry: exports_external.string().min(1),
   version: exports_external.string().optional(),
-  description: 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();
 // ../../packages/kk-core/src/registry.ts
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "fs";
@@ -26152,7 +26155,7 @@ function resolvePluginRoots(opts = {}) {
   if (builtinRoot !== undefined) {
     roots.push({ origin: "builtin", root: builtinRoot });
   }
-  const userRoot = join(opts.homeDir ?? homedir(), ".kk", "plugins");
+  const userRoot = join(opts.homeDir ?? homedir(), ".config", "kk", "plugins");
   if (isDirectory(userRoot)) {
     roots.push({ origin: "user", root: userRoot });
   }
@@ -26330,7 +26333,8 @@ function consumeManifest(dirPath, expectedKind, origin, plugins, diagnostics, se
     manifestPath,
     origin,
     version: manifest.version,
-    description: manifest.description
+    description: manifest.description,
+    ...manifest.operations !== undefined ? { operations: manifest.operations } : {}
   });
 }
 function listSortedDir(absDir) {
@@ -26365,134 +26369,11 @@ init_config();
 if (false) {}
 // src/fanin.ts
 init_dist();
-var EXIT_USAGE = 2;
-var EXIT_INPUT = 1;
-function mergeDocLists(inputs, sources) {
-  const merged = [];
-  const byId = new Map;
-  for (const [i, docList] of inputs.entries()) {
-    const file2 = sources[i] ?? `input[${i}]`;
-    for (const doc2 of docList) {
-      const entry = { file: file2 };
-      if (doc2.sourceUri !== undefined) {
-        entry.sourceUri = doc2.sourceUri;
-      }
-      const existing = byId.get(doc2.id);
-      if (existing) {
-        const list = existing.metadata?.sources;
-        if (Array.isArray(list)) {
-          list.push(entry);
-        }
-        continue;
-      }
-      const mergedDoc = {
-        ...doc2,
-        metadata: { ...doc2.metadata ?? {}, sources: [entry] }
-      };
-      byId.set(doc2.id, mergedDoc);
-      merged.push(mergedDoc);
-    }
-  }
-  return merged;
-}
-async function readDocList(fs2, path3) {
-  if (!await fs2.exists(path3)) {
-    echoError(`Input file does not exist: ${path3}`);
-    return null;
-  }
-  let content;
-  try {
-    content = await fs2.readFile(path3);
-  } catch (err) {
-    echoError(`Failed to read input file ${path3}: ${err instanceof Error ? err.message : String(err)}`);
-    return null;
-  }
-  let json2;
-  try {
-    json2 = JSON.parse(content);
-  } catch (err) {
-    echoError(`Input file ${path3} is invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
-    return null;
-  }
-  const result = DocListSchema.safeParse(json2);
-  if (!result.success) {
-    const issues = result.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ");
-    echoError(`Input file ${path3} violates the Doc list schema: ${issues}`);
-    return null;
-  }
-  return result.data;
-}
-function parseArgs(argv) {
-  const inPaths = [];
-  let outPath;
-  for (let i = 0;i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--in") {
-      const value = argv[++i];
-      if (value === undefined) {
-        throw new Error("--in requires a file path");
-      }
-      inPaths.push(value);
-    } else if (arg === "--out") {
-      const value = argv[++i];
-      if (value === undefined) {
-        throw new Error("--out requires a file path");
-      }
-      if (outPath !== undefined) {
-        throw new Error("--out may be specified only once");
-      }
-      outPath = value;
-    } else {
-      throw new Error(`Unknown argument: ${arg}`);
-    }
-  }
-  if (inPaths.length === 0) {
-    throw new Error("at least one --in file is required");
-  }
-  if (outPath === undefined) {
-    throw new Error("--out file is required");
-  }
-  return { inPaths, outPath };
-}
-async function runFanin(argv) {
-  let opts;
-  try {
-    opts = parseArgs(argv);
-  } catch (err) {
-    echoError(`fanin: ${err instanceof Error ? err.message : String(err)}`);
-    return EXIT_USAGE;
-  }
-  const fs2 = createNodeFileSystem();
-  const inputs = [];
-  const sources = [];
-  for (const inPath of opts.inPaths) {
-    const docList = await readDocList(fs2, inPath);
-    if (docList === null) {
-      return EXIT_INPUT;
-    }
-    inputs.push(docList);
-    sources.push(inPath);
-  }
-  const merged = mergeDocLists(inputs, sources);
-  try {
-    await fs2.writeFile(resolve2(opts.outPath), `${JSON.stringify(merged, null, 2)}
-`);
-  } catch (err) {
-    echoError(`Failed to write output file ${resolve2(opts.outPath)}: ${err instanceof Error ? err.message : String(err)}`);
-    return EXIT_INPUT;
-  }
-  return 0;
-}
-
-// src/fanout.ts
-import { tmpdir } from "os";
-import { isAbsolute as isAbsolute2, join as join3, resolve as resolve4 } from "path";
-init_dist();
 
 // src/invoke.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3, statSync as statSync3, unlinkSync } from "fs";
 import { homedir as homedir2 } from "os";
-import { isAbsolute, join as join2, resolve as resolve3 } from "path";
+import { isAbsolute, join as join2, resolve as resolve2 } from "path";
 init_dist();
 function resolveKkConfigPath() {
   return process.env.KK_CONFIG || join2(homedir2(), ".config/kk/config.yaml");
@@ -26546,12 +26427,21 @@ function pluginEnvFromConfig(kind, name, configFile = resolveKkConfigPath()) {
   }
   return out;
 }
-function spawnPluginEntry(opts) {
-  const cmd = opts.entryPath.endsWith(".ts") || opts.entryPath.endsWith(".js") ? [process.execPath, opts.entryPath, "--in", opts.inPath, "--out", opts.outPath] : [opts.entryPath, "--in", opts.inPath, "--out", opts.outPath];
+function pluginEntryCmd(opts) {
+  return opts.entryPath.endsWith(".ts") || opts.entryPath.endsWith(".js") ? [process.execPath, opts.entryPath, "--in", opts.inPath, "--out", opts.outPath] : [opts.entryPath, "--in", opts.inPath, "--out", opts.outPath];
+}
+function pluginEntryEnv(opts) {
   const fromConfig = opts.pluginKind !== undefined && opts.pluginName !== undefined ? pluginEnvFromConfig(opts.pluginKind, opts.pluginName) : {};
-  const proc = Bun.spawnSync(cmd, {
+  return {
+    ...fromConfig,
+    ...process.env,
+    KNOWLEDGE_KIT_PROJECT_ROOT: process.env.KNOWLEDGE_KIT_PROJECT_ROOT ?? process.cwd()
+  };
+}
+function spawnPluginEntry(opts) {
+  const proc = Bun.spawnSync(pluginEntryCmd(opts), {
     cwd: opts.cwd,
-    env: { ...fromConfig, ...process.env },
+    env: pluginEntryEnv(opts),
     stdout: "pipe",
     stderr: "pipe"
   });
@@ -26561,6 +26451,51 @@ function spawnPluginEntry(opts) {
     stderr: proc.stderr.toString().trim()
   };
 }
+function killProcessTree(pid) {
+  let stdout;
+  try {
+    stdout = Bun.spawnSync(["pgrep", "-P", String(pid)]).stdout.toString();
+  } catch {
+    stdout = "";
+  }
+  for (const line of stdout.trim().split(`
+`)) {
+    const child = Number(line);
+    if (Number.isInteger(child) && child > 0) {
+      killProcessTree(child);
+    }
+  }
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {}
+}
+async function spawnPluginEntryAsync(opts) {
+  let timedOut = false;
+  let timer;
+  const proc = Bun.spawn(pluginEntryCmd(opts), {
+    cwd: opts.cwd,
+    env: pluginEntryEnv(opts),
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  if (opts.timeoutMs !== undefined) {
+    timer = setTimeout(() => {
+      timedOut = true;
+      killProcessTree(proc.pid);
+    }, opts.timeoutMs);
+  }
+  const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+  await proc.exited;
+  if (timer !== undefined) {
+    clearTimeout(timer);
+  }
+  return {
+    exitCode: proc.exitCode === null ? 1 : proc.exitCode,
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+    ...timedOut ? { timedOut: true } : {}
+  };
+}
 async function runInvoke(opts) {
   const discovery = discoverAllPlugins({ pluginsRoot: opts.pluginsRoot, extraPaths: opts.pluginsPath });
   const record2 = getByName(discovery, opts.plugin);
@@ -26574,8 +26509,13 @@ async function runInvoke(opts) {
     return 1;
   }
   const contract = kindContract(record2.kind);
-  const absInPath = resolve3(opts.inPath);
-  const absOutPath = resolve3(opts.outPath);
+  const absInPath = resolve2(opts.inPath);
+  const absOutPath = resolve2(opts.outPath);
+  if (existsSync3(absInPath) && absInPath === absOutPath) {
+    echoError(`--in and --out alias the same path (${absInPath}); refusing to overwrite the input`);
+    return 1;
+  }
+  let artifactOutput = false;
   if (contract.input !== null) {
     if (!existsSync3(absInPath)) {
       echoError(`Input file does not exist: ${absInPath}`);
@@ -26595,11 +26535,26 @@ async function runInvoke(opts) {
       echoError(`Input file ${absInPath} is invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
       return 1;
     }
-    const parseResult = contract.input.safeParse(json2);
-    if (!parseResult.success) {
-      const issues = parseResult.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ");
-      echoError(`Input schema violation for kind '${record2.kind}': ${issues}`);
-      return 1;
+    if (record2.kind === "publish" && Array.isArray(json2)) {
+      const op = Object.values(record2.operations ?? {}).find((o) => o.input === "doc-list");
+      if (!op) {
+        echoError(`Publish plugin '${record2.name}' received a Doc[] array but declares no doc-list operation; a Content object is required`);
+        return 1;
+      }
+      const docs = DocListSchema.safeParse(json2);
+      if (!docs.success) {
+        const issues = docs.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ");
+        echoError(`Input schema violation for the declared doc-list operation of '${record2.name}': ${issues}`);
+        return 1;
+      }
+      artifactOutput = op.output === "markdown";
+    } else {
+      const parseResult = contract.input.safeParse(json2);
+      if (!parseResult.success) {
+        const issues = parseResult.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ");
+        echoError(`Input schema violation for kind '${record2.kind}': ${issues}`);
+        return 1;
+      }
     }
   } else {
     if (!existsSync3(absInPath)) {
@@ -26607,11 +26562,19 @@ async function runInvoke(opts) {
       return 1;
     }
   }
-  const entryPath = isAbsolute(record2.entry) ? record2.entry : resolve3(record2.dir, record2.entry);
+  const entryPath = isAbsolute(record2.entry) ? record2.entry : resolve2(record2.dir, record2.entry);
   if (!existsSync3(entryPath)) {
     echoError(`Plugin entry script does not exist: ${entryPath}`);
     return 1;
   }
+  if (existsSync3(absOutPath)) {
+    try {
+      unlinkSync(absOutPath);
+    } catch (err) {
+      echoError(`Failed to clear stale output ${absOutPath}: ${err instanceof Error ? err.message : String(err)}`);
+      return 1;
+    }
+  }
   const proc = spawnPluginEntry({
     entryPath,
     cwd: record2.dir,
@@ -26630,6 +26593,13 @@ async function runInvoke(opts) {
     echoError(`Plugin entry succeeded but did not write output file: ${absOutPath}`);
     return 1;
   }
+  if (artifactOutput) {
+    if (statSync3(absOutPath).size === 0) {
+      echoError(`Plugin entry succeeded but wrote an empty output file: ${absOutPath}`);
+      return 1;
+    }
+    return 0;
+  }
   let outContent;
   try {
     outContent = readFileSync3(absOutPath, "utf-8");
@@ -26650,10 +26620,305 @@ async function runInvoke(opts) {
     echoError(`Output schema violation for kind '${record2.kind}': ${issues}`);
     return 1;
   }
+  const parsed = outResult.data;
+  if (record2.kind === "publish" && parsed.ok === false) {
+    const reason = parsed.error ?? parsed.message ?? "publish failed";
+    echoError(`Plugin '${record2.name}' reported failure: ${reason}`);
+    return 1;
+  }
+  return 0;
+}
+
+// src/fanin.ts
+var DEFAULT_SOURCE_TIMEOUT_MS = 30 * 60 * 1000;
+var SOURCE_ERROR_MAX_CHARS = 2048;
+function capSourceError(error51) {
+  if (error51.length <= SOURCE_ERROR_MAX_CHARS) {
+    return error51;
+  }
+  return `${error51.slice(0, SOURCE_ERROR_MAX_CHARS)}... [truncated; ${error51.length} chars total]`;
+}
+var EXIT_USAGE = 2;
+var EXIT_INPUT = 1;
+function mergeDocLists(inputs, sources) {
+  const merged = [];
+  const byId = new Map;
+  for (const [i, docList] of inputs.entries()) {
+    const file2 = sources[i] ?? `input[${i}]`;
+    for (const doc2 of docList) {
+      const entry = { file: file2 };
+      if (doc2.sourceUri !== undefined) {
+        entry.sourceUri = doc2.sourceUri;
+      }
+      const existing = byId.get(doc2.id);
+      if (existing) {
+        const list = existing.metadata?.sources;
+        if (Array.isArray(list)) {
+          list.push(entry);
+        }
+        continue;
+      }
+      const mergedDoc = {
+        ...doc2,
+        metadata: { ...doc2.metadata ?? {}, sources: [entry] }
+      };
+      byId.set(doc2.id, mergedDoc);
+      merged.push(mergedDoc);
+    }
+  }
+  return merged;
+}
+async function readDocList(fs2, path3) {
+  if (!await fs2.exists(path3)) {
+    echoError(`Input file does not exist: ${path3}`);
+    return null;
+  }
+  let content;
+  try {
+    content = await fs2.readFile(path3);
+  } catch (err) {
+    echoError(`Failed to read input file ${path3}: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+  let json2;
+  try {
+    json2 = JSON.parse(content);
+  } catch (err) {
+    echoError(`Input file ${path3} is invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+  const result = DocListSchema.safeParse(json2);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ");
+    echoError(`Input file ${path3} violates the Doc list schema: ${issues}`);
+    return null;
+  }
+  return result.data;
+}
+function parseArgs(argv) {
+  const inPaths = [];
+  const sources = [];
+  let outPath;
+  let sourceTimeoutMs;
+  const sourceTimeoutOverrides = {};
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--in") {
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error("--in requires a file path");
+      }
+      inPaths.push(value);
+    } else if (arg === "--source") {
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error("--source requires <plugin>:<inputFile>");
+      }
+      const sep = value.indexOf(":");
+      if (sep <= 0 || sep === value.length - 1) {
+        throw new Error(`--source requires <plugin>:<inputFile>, got '${value}'`);
+      }
+      sources.push({ plugin: value.slice(0, sep), inputFile: value.slice(sep + 1) });
+    } else if (arg === "--source-timeout") {
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error("--source-timeout requires a millisecond value");
+      }
+      if (sourceTimeoutMs !== undefined) {
+        throw new Error("--source-timeout may be specified only once");
+      }
+      const parsed = Number(value);
+      if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`--source-timeout must be a positive integer (ms), got '${value}'`);
+      }
+      sourceTimeoutMs = parsed;
+    } else if (arg === "--source-timeout-override") {
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error("--source-timeout-override requires <plugin>:<ms>");
+      }
+      const sep = value.indexOf(":");
+      if (sep <= 0 || sep === value.length - 1) {
+        throw new Error(`--source-timeout-override requires <plugin>:<ms>, got '${value}'`);
+      }
+      const plugin = value.slice(0, sep);
+      if (plugin in sourceTimeoutOverrides) {
+        throw new Error(`--source-timeout-override: plugin '${plugin}' may be specified only once`);
+      }
+      const parsed = Number(value.slice(sep + 1));
+      if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`--source-timeout-override ms must be a positive integer, got '${value.slice(sep + 1)}'`);
+      }
+      sourceTimeoutOverrides[plugin] = parsed;
+    } else if (arg === "--out") {
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error("--out requires a file path");
+      }
+      if (outPath !== undefined) {
+        throw new Error("--out may be specified only once");
+      }
+      outPath = value;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  if (inPaths.length === 0 && sources.length === 0) {
+    throw new Error("at least one --in file or --source is required");
+  }
+  if (sourceTimeoutMs !== undefined && sources.length === 0) {
+    throw new Error("--source-timeout requires at least one --source");
+  }
+  if (Object.keys(sourceTimeoutOverrides).length > 0 && sources.length === 0) {
+    throw new Error("--source-timeout-override requires at least one --source");
+  }
+  for (const plugin of Object.keys(sourceTimeoutOverrides)) {
+    if (!sources.some((candidate) => candidate.plugin === plugin)) {
+      throw new Error(`--source-timeout-override names plugin '${plugin}' which is not among the --source plugins`);
+    }
+  }
+  if (outPath === undefined) {
+    throw new Error("--out file is required");
+  }
+  return {
+    inPaths,
+    outPath,
+    ...sources.length > 0 ? { sources } : {},
+    ...sourceTimeoutMs !== undefined ? { sourceTimeoutMs } : {},
+    ...Object.keys(sourceTimeoutOverrides).length > 0 ? { sourceTimeoutOverrides } : {}
+  };
+}
+async function collectSourceDocs(discovery, source, timeoutMs) {
+  const record2 = getByName(discovery, source.plugin);
+  if (!record2) {
+    throw new Error(`Plugin '${source.plugin}' not found in the merged plugin registry`);
+  }
+  if (record2.kind !== "ingestion") {
+    throw new Error(`Plugin '${source.plugin}' is kind '${record2.kind}', not 'ingestion'`);
+  }
+  const fs2 = createNodeFileSystem();
+  const absInPath = resolve3(source.inputFile);
+  if (!await fs2.exists(absInPath)) {
+    throw new Error(`Input file does not exist: ${absInPath}`);
+  }
+  const entryPath = isAbsolute2(record2.entry) ? record2.entry : resolve3(record2.dir, record2.entry);
+  if (!await fs2.exists(entryPath)) {
+    throw new Error(`Plugin entry script does not exist: ${entryPath}`);
+  }
+  const outTmp = join3(tmpdir(), `kk-fanin-${source.plugin}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  try {
+    const proc = await spawnPluginEntryAsync({
+      entryPath,
+      cwd: record2.dir,
+      inPath: absInPath,
+      outPath: outTmp,
+      pluginKind: record2.kind,
+      pluginName: record2.name,
+      timeoutMs
+    });
+    if (proc.exitCode !== 0) {
+      const why = proc.timedOut === true ? `timed out after ${timeoutMs}ms` : `exited with code ${proc.exitCode}`;
+      throw new Error(`Plugin '${source.plugin}' ${why}: ${proc.stderr || proc.stdout || "no output"}`);
+    }
+    if (!await fs2.exists(outTmp)) {
+      throw new Error(`Plugin '${source.plugin}' succeeded but did not write an output file`);
+    }
+    let json2;
+    try {
+      json2 = JSON.parse(await fs2.readFile(outTmp));
+    } catch (err) {
+      throw new Error(`Plugin '${source.plugin}' wrote invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsed = DocListSchema.safeParse(json2);
+    if (!parsed.success) {
+      const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ");
+      throw new Error(`Plugin '${source.plugin}' output violates the Doc list schema: ${issues}`);
+    }
+    return parsed.data;
+  } finally {
+    await fs2.deleteFile(outTmp);
+  }
+}
+async function runFanin(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    echoError(`fanin: ${err instanceof Error ? err.message : String(err)}`);
+    return EXIT_USAGE;
+  }
+  const fs2 = createNodeFileSystem();
+  const inputs = [];
+  const sources = [];
+  const sourceErrors = [];
+  for (const inPath of opts.inPaths) {
+    const docList = await readDocList(fs2, inPath);
+    if (docList === null) {
+      return EXIT_INPUT;
+    }
+    inputs.push(docList);
+    sources.push(inPath);
+  }
+  if (opts.sources !== undefined && opts.sources.length > 0) {
+    const discovery = discoverAllPlugins({});
+    const settled = await Promise.allSettled(opts.sources.map(async (source) => {
+      const started = Date.now();
+      try {
+        const timeoutMs = opts.sourceTimeoutOverrides?.[source.plugin] ?? opts.sourceTimeoutMs ?? DEFAULT_SOURCE_TIMEOUT_MS;
+        return { ok: true, docs: await collectSourceDocs(discovery, source, timeoutMs) };
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+          durationMs: Date.now() - started
+        };
+      }
+    }));
+    for (const [i, outcome] of settled.entries()) {
+      const source = opts.sources[i];
+      if (source === undefined) {
+        continue;
+      }
+      const result = outcome.status === "fulfilled" ? outcome.value : { ok: false, error: String(outcome.reason), durationMs: 0 };
+      if (result.ok) {
+        inputs.push(result.docs);
+        sources.push(source.plugin);
+      } else {
+        sourceErrors.push({
+          plugin: source.plugin,
+          error: capSourceError(result.error),
+          durationMs: result.durationMs
+        });
+      }
+    }
+    for (const err of sourceErrors) {
+      echoError(`fanin: source '${err.plugin}' failed after ${err.durationMs}ms: ${err.error}`);
+    }
+    if (sourceErrors.length === opts.sources.length) {
+      echoError(`fanin: all ${opts.sources.length} source(s) failed; no output written`);
+      return EXIT_INPUT;
+    }
+  }
+  const merged = mergeDocLists(inputs, sources);
+  if (sourceErrors.length > 0) {
+    for (const doc2 of merged) {
+      doc2.metadata = { ...doc2.metadata ?? {}, sourceErrors };
+    }
+  }
+  try {
+    await fs2.writeFile(resolve3(opts.outPath), `${JSON.stringify(merged, null, 2)}
+`);
+  } catch (err) {
+    echoError(`Failed to write output file ${resolve3(opts.outPath)}: ${err instanceof Error ? err.message : String(err)}`);
+    return EXIT_INPUT;
+  }
   return 0;
 }
 
 // src/fanout.ts
+import { tmpdir as tmpdir2 } from "os";
+import { isAbsolute as isAbsolute3, join as join4, resolve as resolve4 } from "path";
+init_dist();
 var EXIT_FAILURE = 1;
 var EXIT_INPUT2 = 2;
 function aggregate(entries) {
@@ -26683,6 +26948,7 @@ async function fanout(content, targets, dispatch) {
         status: "published",
         ...result.url !== undefined ? { url: result.url } : {},
         ...result.id !== undefined ? { id: result.id } : {},
+        ...result.metadata !== undefined ? { metadata: result.metadata } : {},
         durationMs
       } : {
         target,
@@ -26704,9 +26970,6 @@ async function fanout(content, targets, dispatch) {
   }
   return aggregate(entries);
 }
-function selectRetryTargets(prior) {
-  return prior.targets.filter((t) => t.status === "failed").map((t) => t.target);
-}
 async function readContent(fs2, path3) {
   if (!await fs2.exists(path3)) {
     echoError(`Content file does not exist: ${path3}`);
@@ -26781,6 +27044,14 @@ async function readAggregateResult(fs2, path3) {
       echoError(`Result file ${path3} violates the aggregate result schema (target ${String(t.target)})`);
       return null;
     }
+    let metadata;
+    if (t.metadata !== undefined) {
+      if (typeof t.metadata !== "object" || t.metadata === null || Array.isArray(t.metadata)) {
+        echoError(`Result file ${path3} violates the aggregate result schema: target '${String(t.target)}' metadata must be an object`);
+        return null;
+      }
+      metadata = t.metadata;
+    }
     targets.push({
       target: t.target,
       ok: t.ok,
@@ -26788,7 +27059,8 @@ async function readAggregateResult(fs2, path3) {
       ...typeof t.url === "string" ? { url: t.url } : {},
       ...typeof t.id === "string" ? { id: t.id } : {},
       ...typeof t.error === "string" ? { error: t.error } : {},
-      ...typeof t.durationMs === "number" ? { durationMs: t.durationMs } : {}
+      ...typeof t.durationMs === "number" ? { durationMs: t.durationMs } : {},
+      ...metadata !== undefined ? { metadata } : {}
     });
   }
   return {
@@ -26887,11 +27159,11 @@ async function pluginDispatch(target, contentPath, discovery) {
     throw new Error(`Publish plugin '${target}' not found in the merged plugin registry`);
   }
   const fs2 = createNodeFileSystem();
-  const entryPath = isAbsolute2(record2.entry) ? record2.entry : resolve4(record2.dir, record2.entry);
+  const entryPath = isAbsolute3(record2.entry) ? record2.entry : resolve4(record2.dir, record2.entry);
   if (!await fs2.exists(entryPath)) {
     throw new Error(`Plugin entry script does not exist: ${entryPath}`);
   }
-  const outTmp = join3(tmpdir(), `kk-fanout-${target}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  const outTmp = join4(tmpdir2(), `kk-fanout-${target}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
   try {
     const proc = spawnPluginEntry({
       entryPath,
@@ -26956,6 +27228,7 @@ async function runFanout(argv, deps = {}) {
   let prior;
   let skipped = [];
   let targets = opts.targets;
+  let retainedFailed = [];
   if (opts.retryFromPath !== undefined) {
     const parsed = await readAggregateResult(fs2, opts.retryFromPath);
     if (parsed === null) {
@@ -26967,17 +27240,26 @@ async function runFanout(argv, deps = {}) {
       ok: true,
       status: "skipped",
       ...t.url !== undefined ? { url: t.url } : {},
-      ...t.id !== undefined ? { id: t.id } : {}
+      ...t.id !== undefined ? { id: t.id } : {},
+      ...t.metadata !== undefined ? { metadata: t.metadata } : {}
     }));
     const carried = new Set(skipped.map((t) => t.target));
-    targets = opts.targets.length > 0 ? opts.targets.filter((t) => !carried.has(t)) : selectRetryTargets(prior);
+    const priorFailed = prior.targets.filter((t) => t.status === "failed");
+    if (opts.targets.length > 0) {
+      const attempt = [...new Set(opts.targets.filter((t) => !carried.has(t)))];
+      const attemptSet = new Set(attempt);
+      targets = attempt;
+      retainedFailed = priorFailed.filter((t) => !attemptSet.has(t.target));
+    } else {
+      targets = priorFailed.map((t) => t.target);
+    }
   }
   const dispatch = deps.dispatch ?? ((t) => pluginDispatch(t, opts.contentPath, discovery));
   if (deps.dispatch === undefined && !validateTargets(targets, discovery)) {
     return EXIT_INPUT2;
   }
   const fresh = await fanout(content, targets, dispatch);
-  const result = prior !== undefined ? aggregate([...skipped, ...fresh.targets]) : fresh;
+  const result = prior !== undefined ? aggregate([...skipped, ...retainedFailed, ...fresh.targets]) : fresh;
   try {
     await fs2.writeFile(resolve4(opts.outPath), `${JSON.stringify(result, null, 2)}
 `);
@@ -27012,11 +27294,24 @@ function collectIn(value, acc) {
   acc.push(value);
   return acc;
 }
+function collectSource(value, acc) {
+  acc.push(value);
+  return acc;
+}
 async function runFaninAction(options) {
   const argv = [];
   for (const inPath of options.in) {
     argv.push("--in", inPath);
   }
+  for (const source of options.source ?? []) {
+    argv.push("--source", source);
+  }
+  if (options.sourceTimeout !== undefined) {
+    argv.push("--source-timeout", options.sourceTimeout);
+  }
+  for (const override of options.sourceTimeoutOverride ?? []) {
+    argv.push("--source-timeout-override", override);
+  }
   argv.push("--out", options.out);
   const code = await runFanin(argv);
   if (code !== 0) {
@@ -27027,6 +27322,10 @@ function collectTarget(value, acc) {
   acc.push(value);
   return acc;
 }
+function collectOverride(value, acc) {
+  acc.push(value);
+  return acc;
+}
 async function runFanoutAction(options) {
   const argv = ["--content", options.content, "--out", options.out];
   for (const target of options.target) {
@@ -27049,10 +27348,10 @@ async function runFanoutAction(options) {
 function registerExecutorCommand(program2) {
   const executor = program2.command("executor").description("Run knowledge-kit plugin steps (invoke, fan-in, fan-out)");
   executor.command("run").description("Invoke a plugin with input/output files and contract validation").argument("<plugin>", "Name of the plugin to invoke").requiredOption("--in <path>", "Input file path (or source path for ingestion)").requiredOption("--out <path>", "Output file path").option("--plugins-root <dir>", "Exclusive root containing plugins (isolation/tests only)").option("--plugins-path <dir>", "Extra plugin root to union with defaults (repeatable)", collectPath, []).action(runInvokeAction);
-  executor.command("fan-in").alias("fanin").description("Merge N Doc[] JSON inputs into one deduplicated Doc[] output").requiredOption("--in <path>", "Input Doc[] JSON file (repeatable)", collectIn, []).requiredOption("--out <path>", "Output merged Doc[] JSON file path").action(runFaninAction);
+  executor.command("fan-in").alias("fanin").description("Merge N Doc[] JSON inputs into one deduplicated Doc[] output").option("--in <path>", "Input Doc[] JSON file (repeatable)", collectIn, []).option("--source <plugin>:<file>", "Ingestion source to spawn concurrently: plugin name and its input file (repeatable)", collectSource, []).option("--source-timeout <ms>", "Per-source timeout in milliseconds (default 1800000)").option("--source-timeout-override <plugin>:<ms>", "Per-source timeout override for one named --source plugin, e.g. horizon-ingest:2700000 (repeatable; wins over --source-timeout/default)", collectOverride, []).requiredOption("--out <path>", "Output merged Doc[] JSON file path").action(runFaninAction);
   executor.command("fan-out").alias("fanout").description("Publish one Content JSON to N targets, aggregating per-target results").requiredOption("--content <path>", "Source ContentSchema JSON file path").option("--target <plugin>", "Target publish plugin name (repeatable)", collectTarget, []).requiredOption("--out <path>", "Aggregate Result JSON file path").option("--retry-from <path>", "Prior Result JSON file to retry only previously failed targets").option("--plugins-root <dir>", "Exclusive root containing plugins (isolation/tests only)").option("--plugins-path <dir>", "Extra plugin root to union with defaults (repeatable)", collectPath, []).action(runFanoutAction);
   program2.command("invoke", { hidden: true }).description("Alias for `executor run` (deprecated)").argument("<plugin>", "Name of the plugin to invoke").requiredOption("--in <path>", "Input file path (or source path for ingestion)").requiredOption("--out <path>", "Output file path").option("--plugins-root <dir>", "Exclusive root containing plugins (isolation/tests only)").option("--plugins-path <dir>", "Extra plugin root to union with defaults (repeatable)", collectPath, []).action(runInvokeAction);
-  program2.command("fanin", { hidden: true }).description("Alias for `executor fan-in` (deprecated)").requiredOption("--in <path>", "Input Doc[] JSON file (repeatable)", collectIn, []).requiredOption("--out <path>", "Output merged Doc[] JSON file path").action(runFaninAction);
+  program2.command("fanin", { hidden: true }).description("Alias for `executor fan-in` (deprecated)").option("--in <path>", "Input Doc[] JSON file (repeatable)", collectIn, []).option("--source <plugin>:<file>", "Ingestion source to spawn concurrently: plugin name and its input file (repeatable)", collectSource, []).option("--source-timeout <ms>", "Per-source timeout in milliseconds (default 1800000)").option("--source-timeout-override <plugin>:<ms>", "Per-source timeout override for one named --source plugin, e.g. horizon-ingest:2700000 (repeatable; wins over --source-timeout/default)", collectOverride, []).requiredOption("--out <path>", "Output merged Doc[] JSON file path").action(runFaninAction);
   program2.command("fanout", { hidden: true }).description("Alias for `executor fan-out` (deprecated)").requiredOption("--content <path>", "Source ContentSchema JSON file path").option("--target <plugin>", "Target publish plugin name (repeatable)", collectTarget, []).requiredOption("--out <path>", "Aggregate Result JSON file path").option("--retry-from <path>", "Prior Result JSON file to retry only previously failed targets").option("--plugins-root <dir>", "Exclusive root containing plugins (isolation/tests only)").option("--plugins-path <dir>", "Extra plugin root to union with defaults (repeatable)", collectPath, []).action(runFanoutAction);
 }