@gobing-ai/knowledge-kit 0.0.21 → 0.0.22

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     },
     "plugins": [
         {
-            "version": "0.0.21",
+            "version": "0.0.22",
             "name": "kk",
             "source": "./plugins/kk",
             "description": "knowledge-kit — a set of toolkit for knowledge management"

package/dist/index.js

@@ -25984,6 +25984,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"),
@@ -26024,10 +26040,7 @@ function collectionForKind(kind) {
   return PLUGIN_KIND_COLLECTIONS[kind];
 }
 function kindForCollection(name) {
-  if (name in PLUGIN_COLLECTION_KINDS) {
-    return PLUGIN_COLLECTION_KINDS[name];
-  }
-  return;
+  return Object.hasOwn(PLUGIN_COLLECTION_KINDS, name) ? PLUGIN_COLLECTION_KINDS[name] : undefined;
 }
 var CONTRACTS = {
   ingestion: { kind: "ingestion", input: null, output: DocListSchema },
@@ -26046,18 +26059,19 @@ function isPluginKind(value) {
 // ../../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()
+});
 // ../../packages/kk-core/src/registry.ts
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "fs";
 import { homedir } from "os";
-import { basename, dirname, join, resolve } from "path";
+import { basename, delimiter, dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 function discoverPlugins(pluginsRoot, origin = "path") {
   const absRoot = resolve(pluginsRoot);
@@ -26106,23 +26120,29 @@ function resolvePluginRoots(opts = {}) {
   if (builtinRoot !== undefined) {
     roots.push({ origin: "builtin", root: builtinRoot });
   }
+  const base = opts.cwd ?? process.cwd();
   const userRoot = join(opts.homeDir ?? homedir(), ".config", "kk", "plugins");
   if (isDirectory(userRoot)) {
     roots.push({ origin: "user", root: userRoot });
   }
-  const projectRoot = join(opts.cwd ?? process.cwd(), "plugins");
+  const projectRoot = join(base, "plugins");
   if (isDirectory(projectRoot) && !(builtinRoot !== undefined && sameRealpath(projectRoot, builtinRoot))) {
     roots.push({ origin: "project", root: projectRoot });
   }
   const env = opts.env ?? process.env;
-  for (const entry of (env.KK_PLUGIN_PATH ?? "").split(":").filter((e) => e !== "")) {
-    if (isDirectory(entry)) {
-      roots.push({ origin: "path", root: entry });
+  for (const entry of (env.KK_PLUGIN_PATH ?? "").split(delimiter).filter((e) => e !== "")) {
+    const abs = resolve(base, entry);
+    if (isDirectory(abs)) {
+      roots.push({ origin: "path", root: abs });
     }
   }
   for (const extra of opts.extraPaths ?? []) {
-    if (extra !== "" && isDirectory(extra)) {
-      roots.push({ origin: "path", root: extra });
+    if (extra === "") {
+      continue;
+    }
+    const abs = resolve(base, extra);
+    if (isDirectory(abs)) {
+      roots.push({ origin: "path", root: abs });
     }
   }
   return roots;
@@ -26173,13 +26193,13 @@ function mergeByName(record2, byName, diagnostics) {
   byName.set(record2.name, record2);
 }
 function resolveBuiltinRoot(injected) {
-  if (injected !== undefined) {
-    return injected;
-  }
-  let dir = dirname(fileURLToPath(import.meta.url));
+  return injected ?? findBuiltinRoot(dirname(fileURLToPath(import.meta.url)));
+}
+function findBuiltinRoot(startDir) {
+  let dir = startDir;
   for (;; ) {
     const candidate = join(dir, "plugins");
-    if (isPluginsTree(candidate)) {
+    if (existsSync(join(dir, "package.json")) && isPluginsTree(candidate)) {
       return candidate;
     }
     const parent = dirname(dir);
@@ -26344,6 +26364,25 @@ if (false) {}
 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 resolve2 } from "path";
+
+// src/plugin-output.ts
+function formatIssues(error51) {
+  return error51.issues.map((i) => `${i.path.map(String).join(".") || "root"}: ${i.message}`).join("; ");
+}
+async function readPluginJson(fs2, path3, schema, label, violation) {
+  let json2;
+  try {
+    json2 = JSON.parse(await fs2.readFile(path3));
+  } catch (err) {
+    throw new Error(`${label} wrote invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const parsed = schema.safeParse(json2);
+  if (!parsed.success)
+    throw new Error(`${label} ${violation}: ${formatIssues(parsed.error)}`);
+  return parsed.data;
+}
+
+// src/invoke.ts
 function resolveKkConfigPath() {
   return process.env.KK_CONFIG || join2(homedir2(), ".config/kk/config.yaml");
 }
@@ -26479,6 +26518,13 @@ async function spawnPluginEntryAsync(opts) {
     ...timedOut ? { timedOut: true } : {}
   };
 }
+function isSameFile(a, b) {
+  if (!existsSync3(b))
+    return false;
+  const sa = statSync3(a);
+  const sb = statSync3(b);
+  return sa.dev === sb.dev && sa.ino === sb.ino;
+}
 async function runInvoke(opts) {
   const discovery = discoverAllPlugins({ pluginsRoot: opts.pluginsRoot, extraPaths: opts.pluginsPath });
   const record2 = getByName(discovery, opts.plugin);
@@ -26494,7 +26540,7 @@ async function runInvoke(opts) {
   const contract = kindContract(record2.kind);
   const absInPath = resolve2(opts.inPath);
   const absOutPath = resolve2(opts.outPath);
-  if (existsSync3(absInPath) && absInPath === absOutPath) {
+  if (existsSync3(absInPath) && (absInPath === absOutPath || isSameFile(absInPath, absOutPath))) {
     echoError(`--in and --out alias the same path (${absInPath}); refusing to overwrite the input`);
     return 1;
   }
@@ -26526,16 +26572,14 @@ async function runInvoke(opts) {
       }
       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}`);
+        echoError(`Input schema violation for the declared doc-list operation of '${record2.name}': ${formatIssues(docs.error)}`);
         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}`);
+        echoError(`Input schema violation for kind '${record2.kind}': ${formatIssues(parseResult.error)}`);
         return 1;
       }
     }
@@ -26569,8 +26613,7 @@ async function runInvoke(opts) {
   if (proc.exitCode !== 0) {
     const errMsg = proc.stderr || proc.stdout || `Plugin entry exited with code ${proc.exitCode}`;
     echoError(`Plugin entry '${record2.name}' failed (exit code ${proc.exitCode}): ${errMsg}`);
-    const exitCode = proc.exitCode !== 0 ? proc.exitCode : 1;
-    return exitCode;
+    return proc.exitCode;
   }
   if (!existsSync3(absOutPath)) {
     echoError(`Plugin entry succeeded but did not write output file: ${absOutPath}`);
@@ -26599,8 +26642,7 @@ async function runInvoke(opts) {
   }
   const outResult = contract.output.safeParse(outJson);
   if (!outResult.success) {
-    const issues = outResult.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ");
-    echoError(`Output schema violation for kind '${record2.kind}': ${issues}`);
+    echoError(`Output schema violation for kind '${record2.kind}': ${formatIssues(outResult.error)}`);
     return 1;
   }
   const parsed = outResult.data;
@@ -26672,8 +26714,7 @@ async function readDocList(fs2, path3) {
   }
   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}`);
+    echoError(`Input file ${path3} violates the Doc list schema: ${formatIssues(result.error)}`);
     return null;
   }
   return result.data;
@@ -26684,6 +26725,8 @@ function parseArgs(argv) {
   let outPath;
   let sourceTimeoutMs;
   const sourceTimeoutOverrides = {};
+  let pluginsRoot;
+  const pluginsPath = [];
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--in") {
@@ -26742,6 +26785,21 @@ function parseArgs(argv) {
         throw new Error("--out may be specified only once");
       }
       outPath = value;
+    } else if (arg === "--plugins-root") {
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error("--plugins-root requires a directory path");
+      }
+      if (pluginsRoot !== undefined) {
+        throw new Error("--plugins-root may be specified only once");
+      }
+      pluginsRoot = value;
+    } else if (arg === "--plugins-path") {
+      const value = argv[++i];
+      if (value === undefined) {
+        throw new Error("--plugins-path requires a directory path");
+      }
+      pluginsPath.push(value);
     } else {
       throw new Error(`Unknown argument: ${arg}`);
     }
@@ -26768,7 +26826,9 @@ function parseArgs(argv) {
     outPath,
     ...sources.length > 0 ? { sources } : {},
     ...sourceTimeoutMs !== undefined ? { sourceTimeoutMs } : {},
-    ...Object.keys(sourceTimeoutOverrides).length > 0 ? { sourceTimeoutOverrides } : {}
+    ...Object.keys(sourceTimeoutOverrides).length > 0 ? { sourceTimeoutOverrides } : {},
+    ...pluginsRoot !== undefined ? { pluginsRoot } : {},
+    ...pluginsPath.length > 0 ? { pluginsPath } : {}
   };
 }
 async function collectSourceDocs(discovery, source, timeoutMs) {
@@ -26806,18 +26866,7 @@ async function collectSourceDocs(discovery, source, timeoutMs) {
     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;
+    return readPluginJson(fs2, outTmp, DocListSchema, `Plugin '${source.plugin}'`, "output violates the Doc list schema");
   } finally {
     await fs2.deleteFile(outTmp);
   }
@@ -26830,6 +26879,10 @@ async function runFanin(argv) {
     echoError(`fanin: ${err instanceof Error ? err.message : String(err)}`);
     return EXIT_USAGE;
   }
+  if (opts.pluginsRoot !== undefined && (opts.pluginsPath?.length ?? 0) > 0) {
+    echoError("fanin: --plugins-root and --plugins-path are mutually exclusive (ADR-012 R6)");
+    return EXIT_USAGE;
+  }
   const fs2 = createNodeFileSystem();
   const inputs = [];
   const sources = [];
@@ -26843,7 +26896,7 @@ async function runFanin(argv) {
     sources.push(inPath);
   }
   if (opts.sources !== undefined && opts.sources.length > 0) {
-    const discovery = discoverAllPlugins({});
+    const discovery = discoverAllPlugins({ pluginsRoot: opts.pluginsRoot, extraPaths: opts.pluginsPath });
     const settled = await Promise.allSettled(opts.sources.map(async (source) => {
       const started = Date.now();
       try {
@@ -26973,12 +27026,34 @@ async function readContent(fs2, path3) {
   }
   const result = ContentSchema.safeParse(json2);
   if (!result.success) {
-    const issues = result.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ");
-    echoError(`Content file ${path3} violates the Content schema: ${issues}`);
+    echoError(`Content file ${path3} violates the Content schema: ${formatIssues(result.error)}`);
     return null;
   }
   return result.data;
 }
+function describeAggregateIssue(json2, issue2) {
+  if (issue2 === undefined)
+    return " (ok/summary/targets)";
+  const path3 = issue2.path.map(String);
+  const targets = json2.targets;
+  const targetName = (index) => {
+    const entry = Array.isArray(targets) ? targets[index] : undefined;
+    if (typeof entry !== "object" || entry === null)
+      return "undefined";
+    return String(entry.target);
+  };
+  if (path3[0] === "targets" && path3.length >= 2) {
+    const index = Number(path3[1]);
+    if (path3.length === 2)
+      return " (target entry)";
+    if (path3[2] === "metadata")
+      return `: target '${targetName(index)}' metadata must be an object`;
+    return ` (target ${targetName(index)})`;
+  }
+  if (path3[0] === "summary" && path3.length >= 2)
+    return ` (summary.${path3[1]})`;
+  return " (ok/summary/targets)";
+}
 async function readAggregateResult(fs2, path3) {
   if (!await fs2.exists(path3)) {
     echoError(`Result file does not exist: ${path3}`);
@@ -26998,63 +27073,16 @@ async function readAggregateResult(fs2, path3) {
     echoError(`Result file ${path3} is invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
     return null;
   }
-  if (typeof json2 !== "object" || json2 === null) {
+  if (typeof json2 !== "object" || json2 === null || Array.isArray(json2)) {
     echoError(`Result file ${path3} is not an aggregate result object`);
     return null;
   }
-  const obj = json2;
-  const summary = obj.summary;
-  if (typeof obj.ok !== "boolean" || typeof summary !== "object" || summary === null || !Array.isArray(obj.targets)) {
-    echoError(`Result file ${path3} violates the aggregate result schema (ok/summary/targets)`);
+  const parsed = AggregateResultSchema.safeParse(json2);
+  if (!parsed.success) {
+    echoError(`Result file ${path3} violates the aggregate result schema${describeAggregateIssue(json2, parsed.error.issues[0])}`);
     return null;
   }
-  const sum = summary;
-  for (const key of ["total", "succeeded", "failed", "skipped"]) {
-    if (typeof sum[key] !== "number") {
-      echoError(`Result file ${path3} violates the aggregate result schema (summary.${key})`);
-      return null;
-    }
-  }
-  const targets = [];
-  for (const entry of obj.targets) {
-    if (typeof entry !== "object" || entry === null) {
-      echoError(`Result file ${path3} violates the aggregate result schema (target entry)`);
-      return null;
-    }
-    const t = entry;
-    if (typeof t.target !== "string" || typeof t.ok !== "boolean" || t.status !== "published" && t.status !== "failed" && t.status !== "skipped") {
-      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,
-      status: t.status,
-      ...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 } : {},
-      ...metadata !== undefined ? { metadata } : {}
-    });
-  }
-  return {
-    ok: obj.ok,
-    summary: {
-      total: sum.total,
-      succeeded: sum.succeeded,
-      failed: sum.failed,
-      skipped: sum.skipped
-    },
-    targets
-  };
+  return parsed.data;
 }
 function parseArgs2(argv) {
   const targets = [];
@@ -27161,12 +27189,7 @@ async function pluginDispatch(target, contentPath, discovery) {
     if (!await fs2.exists(outTmp)) {
       throw new Error(`Plugin '${target}' succeeded but did not write a result file`);
     }
-    const parsed = ResultSchema.safeParse(JSON.parse(await fs2.readFile(outTmp)));
-    if (!parsed.success) {
-      const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ");
-      throw new Error(`Plugin '${target}' wrote an invalid Result: ${issues}`);
-    }
-    return parsed.data;
+    return readPluginJson(fs2, outTmp, ResultSchema, `Plugin '${target}'`, "wrote an invalid Result");
   } finally {
     await fs2.deleteFile(outTmp);
   }
@@ -27209,7 +27232,7 @@ async function runFanout(argv, deps = {}) {
   const discovery = discoverAllPlugins({ pluginsRoot, extraPaths: opts.pluginsPath });
   let prior;
   let skipped = [];
-  let targets = opts.targets;
+  let targets = [...new Set(opts.targets)];
   let retainedFailed = [];
   if (opts.retryFromPath !== undefined) {
     const parsed = await readAggregateResult(fs2, opts.retryFromPath);
@@ -27253,7 +27276,7 @@ async function runFanout(argv, deps = {}) {
 }
 
 // src/commands/executor.ts
-function collectPath(value, acc) {
+function collectRepeatable(value, acc) {
   acc.push(value);
   return acc;
 }
@@ -27272,14 +27295,6 @@ async function runInvokeAction(plugin, options) {
     throw new CommanderError(code, "kk.executor.run.failed", `invoke failed with exit code ${code}`);
   }
 }
-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) {
@@ -27295,19 +27310,17 @@ async function runFaninAction(options) {
     argv.push("--source-timeout-override", override);
   }
   argv.push("--out", options.out);
+  if (options.pluginsRoot !== undefined) {
+    argv.push("--plugins-root", options.pluginsRoot);
+  }
+  for (const path3 of options.pluginsPath ?? []) {
+    argv.push("--plugins-path", path3);
+  }
   const code = await runFanin(argv);
   if (code !== 0) {
     throw new CommanderError(code, "kk.executor.fanin.failed", `fan-in failed with exit code ${code}`);
   }
 }
-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) {
@@ -27327,14 +27340,23 @@ async function runFanoutAction(options) {
     throw new CommanderError(code, "kk.executor.fanout.failed", `fan-out failed with exit code ${code}`);
   }
 }
+function withRunOptions(cmd) {
+  return cmd.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)", collectRepeatable, []);
+}
+function withFaninOptions(cmd) {
+  return cmd.option("--in <path>", "Input Doc[] JSON file (repeatable)", collectRepeatable, []).option("--source <plugin>:<file>", "Ingestion source to spawn concurrently: plugin name and its input file (repeatable)", collectRepeatable, []).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)", collectRepeatable, []).requiredOption("--out <path>", "Output merged Doc[] JSON 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)", collectRepeatable, []);
+}
+function withFanoutOptions(cmd) {
+  return cmd.requiredOption("--content <path>", "Source ContentSchema JSON file path").option("--target <plugin>", "Target publish plugin name (repeatable)", collectRepeatable, []).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)", collectRepeatable, []);
+}
 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").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)").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);
+  withRunOptions(executor.command("run").description("Invoke a plugin with input/output files and contract validation").argument("<plugin>", "Name of the plugin to invoke")).action(runInvokeAction);
+  withFaninOptions(executor.command("fan-in").alias("fanin").description("Merge N Doc[] JSON inputs into one deduplicated Doc[] output")).action(runFaninAction);
+  withFanoutOptions(executor.command("fan-out").alias("fanout").description("Publish one Content JSON to N targets, aggregating per-target results")).action(runFanoutAction);
+  withRunOptions(program2.command("invoke", { hidden: true }).description("Alias for `executor run` (deprecated)").argument("<plugin>", "Name of the plugin to invoke")).action(runInvokeAction);
+  withFaninOptions(program2.command("fanin", { hidden: true }).description("Alias for `executor fan-in` (deprecated)")).action(runFaninAction);
+  withFanoutOptions(program2.command("fanout", { hidden: true }).description("Alias for `executor fan-out` (deprecated)")).action(runFanoutAction);
 }
 
 // src/commands/plugin.ts
@@ -27355,7 +27377,7 @@ var consoleOutput = {
 };
 
 // src/commands/plugin.ts
-function collectPath2(value, acc) {
+function collectPath(value, acc) {
   acc.push(value);
   return acc;
 }
@@ -27384,25 +27406,21 @@ function printDiagnostics(report) {
   for (const p of report.plugins) {
     all.push(...p.diagnostics);
   }
-  echoError(`Found ${all.length} diagnostic issue(s):
-`);
+  echoError(`Found ${all.length} diagnostic issue(s):`);
   for (const d of all) {
-    echoError(`  [${d.code}] ${d.path}: ${d.reason}
-`);
+    echoError(`  [${d.code}] ${d.path}: ${d.reason}`);
   }
 }
 function statusAction(options) {
   if (options.pluginsRoot !== undefined && (options.pluginsPath?.length ?? 0) > 0) {
-    echoError(`--plugins-root and --plugins-path are mutually exclusive (ADR-012 R6)
-`);
+    echoError("--plugins-root and --plugins-path are mutually exclusive (ADR-012 R6)");
     throw new CommanderError(2, "kk.plugin.root-path-conflict", "--plugins-root and --plugins-path are mutually exclusive");
   }
   const report = buildStatusReport({ pluginsRoot: options.pluginsRoot, pluginsPath: options.pluginsPath });
   let records = report.plugins;
   if (options.kind) {
     if (!isPluginKind(options.kind)) {
-      echoError(`Invalid plugin kind: ${options.kind}
-`);
+      echoError(`Invalid plugin kind: ${options.kind}`);
       throw new CommanderError(1, "kk.plugin.invalid-kind", `invalid plugin kind: ${options.kind}`);
     }
     records = report.plugins.filter((p) => p.kind === options.kind);
@@ -27446,7 +27464,7 @@ function statusAction(options) {
   }
 }
 function registerStatusVerb(parent, name, description, hidden) {
-  parent.command(name, { hidden }).description(description).option("--kind <kind>", "Filter plugins by kind (ingestion, generator, publish)").option("--json", "Output machine-readable unified health report").option("--plugins-root <dir>", "Exclusive root containing plugins (isolation/tests only)").option("--plugins-path <dir>", "Extra plugin root to union with defaults (repeatable)", collectPath2, []).action(statusAction);
+  parent.command(name, { hidden }).description(description).option("--kind <kind>", "Filter plugins by kind (ingestion, generator, publish)").option("--json", "Output machine-readable unified health report").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(statusAction);
 }
 function registerPluginCommand(program2) {
   const plugin = program2.command("plugin").description("Inspect and validate knowledge-kit plugins");
@@ -27464,7 +27482,8 @@ import { spawnSync } from "child_process";
 import { existsSync as existsSync5, realpathSync as realpathSync3 } from "fs";
 import { dirname as dirname3, join as join5, resolve as resolve6 } from "path";
 var STAGES_REL = "plugins/kk/scripts/kk-workflow-stages.ts";
-function resolveStagesScript(argv1 = process.argv[1]) {
+var CHECKOUT_ROOT = resolve6(import.meta.dir, "../../..");
+function resolveStagesScript(argv1 = process.argv[1], checkoutRoot = CHECKOUT_ROOT) {
   let fromPkg = "";
   if (argv1) {
     try {
@@ -27475,9 +27494,9 @@ function resolveStagesScript(argv1 = process.argv[1]) {
   }
   if (fromPkg && existsSync5(fromPkg))
     return fromPkg;
-  const fromCwd = resolve6(STAGES_REL);
-  if (existsSync5(fromCwd))
-    return fromCwd;
+  const fromCheckout = join5(checkoutRoot, STAGES_REL);
+  if (existsSync5(fromCheckout))
+    return fromCheckout;
   throw new Error(`kk-workflow-stages.ts not found at ${fromPkg || STAGES_REL} \u2014 install or refresh the kk package (bun link in a checkout)`);
 }
 function runStage(args, execPath = process.execPath, argv1) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/knowledge-kit",
-    "version": "0.0.21",
+    "version": "0.0.22",
     "description": "An ingest → create → publish content pipeline CLI (Bun).",
     "repository": {
         "type": "git",

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

@@ -21780,6 +21780,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"),
@@ -21808,14 +21824,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();