@gobing-ai/knowledge-kit 0.0.3 → 0.0.5

package/dist/index.js

@@ -14308,12 +14308,6 @@ var logger = {
     Bun.write(Bun.stdout, encoder.encode(text));
   }
 };
-
-// ../../packages/utils/src/index.ts
-function add(a, b) {
-  return a + b;
-}
-
 // ../../node_modules/.bun/commander@15.0.0/node_modules/commander/lib/error.js
 class CommanderError extends Error {
   constructor(exitCode, code, message) {
@@ -16358,15 +16352,6 @@ function useColor() {
 // ../../node_modules/.bun/commander@15.0.0/node_modules/commander/index.js
 var program = new Command;
 
-// src/commands/add.ts
-function registerAddCommand(program2) {
-  const parseIntArg = (v) => Number.parseInt(v, 10);
-  program2.command("add").description("Add two numbers").argument("<a>", "first number", parseIntArg).argument("<b>", "second number", parseIntArg).action((a, b) => {
-    logger.out(`${add(a, b)}
-`);
-  });
-}
-
 // src/fanin.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { resolve as resolve2 } from "path";
@@ -16441,9 +16426,11 @@ var PluginManifestSchema = exports_external.object({
   description: exports_external.string().optional()
 }).passthrough();
 // ../../packages/kk-core/src/registry.ts
-import { existsSync, readdirSync, readFileSync, statSync } from "fs";
-import { basename, join, resolve } from "path";
-function discoverPlugins(pluginsRoot) {
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "fs";
+import { homedir } from "os";
+import { basename, dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+function discoverPlugins(pluginsRoot, origin = "path") {
   const absRoot = resolve(pluginsRoot);
   const plugins = [];
   const diagnostics = [];
@@ -16454,7 +16441,7 @@ function discoverPlugins(pluginsRoot) {
   }
   const rootAsCollection = kindForCollection(basename(absRoot));
   if (rootAsCollection) {
-    scanCollection(absRoot, rootAsCollection, plugins, diagnostics, seenNames);
+    scanCollection(absRoot, rootAsCollection, origin, plugins, diagnostics, seenNames);
     return { plugins, diagnostics };
   }
   for (const entryName of entries.names) {
@@ -16467,7 +16454,7 @@ function discoverPlugins(pluginsRoot) {
     }
     const expectedKind = kindForCollection(entryName);
     if (expectedKind) {
-      scanCollection(dirPath, expectedKind, plugins, diagnostics, seenNames);
+      scanCollection(dirPath, expectedKind, origin, plugins, diagnostics, seenNames);
       continue;
     }
     const strayManifest = join(dirPath, "plugin.json");
@@ -16481,7 +16468,117 @@ function discoverPlugins(pluginsRoot) {
   }
   return { plugins, diagnostics };
 }
-function scanCollection(collectionDir, expectedKind, plugins, diagnostics, seenNames) {
+function resolvePluginRoots(opts = {}) {
+  if (opts.pluginsRoot !== undefined) {
+    return [{ origin: "path", root: opts.pluginsRoot }];
+  }
+  const roots = [];
+  const builtinRoot = resolveBuiltinRoot(opts.packagePluginsRoot);
+  if (builtinRoot !== undefined) {
+    roots.push({ origin: "builtin", root: builtinRoot });
+  }
+  const userRoot = join(opts.homeDir ?? homedir(), ".kk", "plugins");
+  if (isDirectory(userRoot)) {
+    roots.push({ origin: "user", root: userRoot });
+  }
+  const projectRoot = join(opts.cwd ?? process.cwd(), "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 extra of opts.extraPaths ?? []) {
+    if (extra !== "" && isDirectory(extra)) {
+      roots.push({ origin: "path", root: extra });
+    }
+  }
+  return roots;
+}
+function discoverAllPlugins(opts = {}) {
+  const roots = resolvePluginRoots(opts);
+  const diagnostics = [];
+  const byName = new Map;
+  const scannedRealpaths = new Set;
+  for (const { origin, root } of roots) {
+    let real;
+    try {
+      real = realpathSync(root);
+    } catch {
+      continue;
+    }
+    if (scannedRealpaths.has(real)) {
+      continue;
+    }
+    scannedRealpaths.add(real);
+    if (origin === "path" && existsSync(join(root, "plugin.json"))) {
+      const records = [];
+      const rootDiagnostics = [];
+      consumeManifest(root, null, origin, records, rootDiagnostics, new Set);
+      diagnostics.push(...rootDiagnostics);
+      for (const record2 of records) {
+        mergeByName(record2, byName, diagnostics);
+      }
+      continue;
+    }
+    const scan = discoverPlugins(root, origin);
+    diagnostics.push(...scan.diagnostics);
+    for (const record2 of scan.plugins) {
+      mergeByName(record2, byName, diagnostics);
+    }
+  }
+  return { plugins: [...byName.values()], diagnostics };
+}
+function mergeByName(record2, byName, diagnostics) {
+  const existing = byName.get(record2.name);
+  if (existing !== undefined) {
+    diagnostics.push({
+      code: "shadowed",
+      path: existing.manifestPath,
+      reason: `Plugin name "${record2.name}" shadowed by ` + `${record2.manifestPath} (origin: ${record2.origin})`
+    });
+  }
+  byName.set(record2.name, record2);
+}
+function resolveBuiltinRoot(injected) {
+  if (injected !== undefined) {
+    return injected;
+  }
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (;; ) {
+    const candidate = join(dir, "plugins");
+    if (isPluginsTree(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return;
+    }
+    dir = parent;
+  }
+}
+function isPluginsTree(dir) {
+  if (!isDirectory(dir)) {
+    return false;
+  }
+  for (const collection of Object.keys(PLUGIN_COLLECTION_KINDS)) {
+    if (isDirectory(join(dir, collection))) {
+      return true;
+    }
+  }
+  return false;
+}
+function sameRealpath(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+function scanCollection(collectionDir, expectedKind, origin, plugins, diagnostics, seenNames) {
   const entries = listSortedDir(collectionDir);
   if (!entries.ok) {
     diagnostics.push(entries.diagnostic);
@@ -16492,15 +16589,23 @@ function scanCollection(collectionDir, expectedKind, plugins, diagnostics, seenN
     if (!isDirectory(dirPath)) {
       continue;
     }
-    consumeManifest(dirPath, expectedKind, plugins, diagnostics, seenNames);
+    consumeManifest(dirPath, expectedKind, origin, plugins, diagnostics, seenNames);
   }
 }
-function consumeManifest(dirPath, expectedKind, plugins, diagnostics, seenNames) {
+function consumeManifest(dirPath, expectedKind, origin, plugins, diagnostics, seenNames) {
   const manifestPath = join(dirPath, "plugin.json");
   let content;
   try {
     content = readFileSync(manifestPath, "utf-8");
-  } catch {
+  } catch (err) {
+    if (err?.code === "ENOENT") {
+      return;
+    }
+    diagnostics.push({
+      code: "unreadable",
+      path: manifestPath,
+      reason: err instanceof Error ? err.message : String(err)
+    });
     return;
   }
   let json2;
@@ -16525,7 +16630,7 @@ function consumeManifest(dirPath, expectedKind, plugins, diagnostics, seenNames)
     return;
   }
   const manifest = parsed.data;
-  if (manifest.kind !== expectedKind) {
+  if (expectedKind !== null && manifest.kind !== expectedKind) {
     diagnostics.push({
       code: "kind_mismatch",
       path: manifestPath,
@@ -16548,6 +16653,7 @@ function consumeManifest(dirPath, expectedKind, plugins, diagnostics, seenNames)
     entry: manifest.entry,
     dir: dirPath,
     manifestPath,
+    origin,
     version: manifest.version,
     description: manifest.description
   });
@@ -16573,9 +16679,6 @@ function isDirectory(path2) {
     return false;
   }
 }
-function listByKind(result, kind) {
-  return result.plugins.filter((p) => p.kind === kind);
-}
 function getByName(result, name) {
   return result.plugins.find((p) => p.name === name);
 }
@@ -16698,25 +16801,6 @@ async function runFanin(argv) {
   return 0;
 }
 
-// src/commands/fanin.ts
-function registerFaninCommand(program2) {
-  const collectIn = (value, acc) => {
-    acc.push(value);
-    return acc;
-  };
-  program2.command("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(async (options) => {
-    const argv = [];
-    for (const inPath of options.in) {
-      argv.push("--in", inPath);
-    }
-    argv.push("--out", options.out);
-    const code = await runFanin(argv);
-    if (code !== 0) {
-      throw new CommanderError(code, "kk.fanin.failed", `fanin failed with exit code ${code}`);
-    }
-  });
-}
-
 // src/fanout.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4, rmSync, writeFileSync as writeFileSync2 } from "fs";
 import { tmpdir } from "os";
@@ -16740,11 +16824,10 @@ function spawnPluginEntry(opts) {
   };
 }
 async function runInvoke(opts) {
-  const pluginsRoot = opts.pluginsRoot ?? "./plugins";
-  const discovery = discoverPlugins(pluginsRoot);
+  const discovery = discoverAllPlugins({ pluginsRoot: opts.pluginsRoot, extraPaths: opts.pluginsPath });
   const record2 = getByName(discovery, opts.plugin);
   if (!record2) {
-    logger.error(`Plugin '${opts.plugin}' not found under ${resolve3(pluginsRoot)}`);
+    logger.error(`Plugin '${opts.plugin}' not found in the merged plugin registry`);
     if (discovery.diagnostics.length > 0) {
       for (const diag of discovery.diagnostics) {
         logger.error(`  [diagnostic] ${diag.code} at ${diag.path}: ${diag.reason}`);
@@ -16981,6 +17064,7 @@ function readAggregateResult(path2) {
 }
 function parseArgs2(argv) {
   const targets = [];
+  const pluginsPath = [];
   let contentPath;
   let outPath;
   let retryFromPath;
@@ -17029,6 +17113,12 @@ function parseArgs2(argv) {
         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}`);
     }
@@ -17047,13 +17137,14 @@ function parseArgs2(argv) {
     targets,
     outPath,
     ...retryFromPath !== undefined ? { retryFromPath } : {},
-    ...pluginsRoot !== undefined ? { pluginsRoot } : {}
+    ...pluginsRoot !== undefined ? { pluginsRoot } : {},
+    ...pluginsPath.length > 0 ? { pluginsPath } : {}
   };
 }
-async function pluginDispatch(target, contentPath, pluginsRoot) {
-  const record2 = getByName(discoverPlugins(pluginsRoot), target);
+async function pluginDispatch(target, contentPath, discovery) {
+  const record2 = getByName(discovery, target);
   if (record2?.kind !== "publish") {
-    throw new Error(`Publish plugin '${target}' not found under ${resolve4(pluginsRoot)}`);
+    throw new Error(`Publish plugin '${target}' not found in the merged plugin registry`);
   }
   const entryPath = isAbsolute2(record2.entry) ? record2.entry : resolve4(record2.dir, record2.entry);
   if (!existsSync4(entryPath)) {
@@ -17083,8 +17174,7 @@ async function pluginDispatch(target, contentPath, pluginsRoot) {
     rmSync(outTmp, { force: true });
   }
 }
-function validateTargets(targets, pluginsRoot) {
-  const discovery = discoverPlugins(pluginsRoot);
+function validateTargets(targets, discovery) {
   const missing = [];
   for (const target of targets) {
     const record2 = getByName(discovery, target);
@@ -17093,7 +17183,7 @@ function validateTargets(targets, pluginsRoot) {
     }
   }
   if (missing.length > 0) {
-    logger.error(`Unknown publish target(s): ${missing.join(", ")} under ${resolve4(pluginsRoot)}`);
+    logger.error(`Unknown publish target(s): ${missing.join(", ")}`);
     for (const diag of discovery.diagnostics) {
       logger.error(`  [diagnostic] ${diag.code} at ${diag.path}: ${diag.reason}`);
     }
@@ -17113,7 +17203,12 @@ async function runFanout(argv, deps = {}) {
   if (content === null) {
     return EXIT_INPUT2;
   }
-  const pluginsRoot = deps.pluginsRoot ?? opts.pluginsRoot ?? "./plugins";
+  if (opts.pluginsRoot !== undefined && (opts.pluginsPath?.length ?? 0) > 0) {
+    logger.error("--plugins-root and --plugins-path are mutually exclusive (ADR-012 R6)");
+    return EXIT_INPUT2;
+  }
+  const pluginsRoot = deps.pluginsRoot ?? opts.pluginsRoot;
+  const discovery = discoverAllPlugins({ pluginsRoot, extraPaths: opts.pluginsPath });
   let prior;
   let skipped = [];
   let targets = opts.targets;
@@ -17133,8 +17228,8 @@ async function runFanout(argv, deps = {}) {
     const carried = new Set(skipped.map((t) => t.target));
     targets = opts.targets.length > 0 ? opts.targets.filter((t) => !carried.has(t)) : selectRetryTargets(prior);
   }
-  const dispatch = deps.dispatch ?? ((t) => pluginDispatch(t, opts.contentPath, pluginsRoot));
-  if (deps.dispatch === undefined && !validateTargets(targets, pluginsRoot)) {
+  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);
@@ -17149,130 +17244,185 @@ async function runFanout(argv, deps = {}) {
   return result.ok ? 0 : EXIT_FAILURE;
 }
 
-// src/commands/fanout.ts
-function registerFanoutCommand(program2) {
-  const collectTarget = (value, acc) => {
-    acc.push(value);
-    return acc;
-  };
-  program2.command("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>", "Root directory containing plugins").action(async (options) => {
-    const argv = ["--content", options.content, "--out", options.out];
-    for (const target of options.target) {
-      argv.push("--target", target);
-    }
-    if (options.retryFrom) {
-      argv.push("--retry-from", options.retryFrom);
-    }
-    if (options.pluginsRoot) {
-      argv.push("--plugins-root", options.pluginsRoot);
-    }
-    const code = await runFanout(argv);
-    if (code !== 0) {
-      throw new CommanderError(code, "kk.fanout.failed", `fanout failed with exit code ${code}`);
-    }
+// src/commands/executor.ts
+function collectPath(value, acc) {
+  acc.push(value);
+  return acc;
+}
+async function runInvokeAction(plugin, options) {
+  if (options.pluginsRoot !== undefined && (options.pluginsPath?.length ?? 0) > 0) {
+    throw new CommanderError(2, "kk.executor.run.root-path-conflict", "--plugins-root and --plugins-path are mutually exclusive");
+  }
+  const code = await runInvoke({
+    plugin,
+    inPath: options.in,
+    outPath: options.out,
+    pluginsRoot: options.pluginsRoot,
+    pluginsPath: options.pluginsPath
   });
+  if (code !== 0) {
+    throw new CommanderError(code, "kk.executor.run.failed", `invoke failed with exit code ${code}`);
+  }
 }
-
-// src/commands/invoke.ts
-function registerInvokeCommand(program2) {
-  program2.command("invoke").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>", "Root directory containing plugins").action(async (plugin, options) => {
-    const code = await runInvoke({
-      plugin,
-      inPath: options.in,
-      outPath: options.out,
-      pluginsRoot: options.pluginsRoot
-    });
-    if (code !== 0) {
-      throw new CommanderError(code, "kk.invoke.failed", `invoke failed with exit code ${code}`);
-    }
-  });
+function collectIn(value, acc) {
+  acc.push(value);
+  return acc;
+}
+async function runFaninAction(options) {
+  const argv = [];
+  for (const inPath of options.in) {
+    argv.push("--in", inPath);
+  }
+  argv.push("--out", options.out);
+  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;
+}
+async function runFanoutAction(options) {
+  const argv = ["--content", options.content, "--out", options.out];
+  for (const target of options.target) {
+    argv.push("--target", target);
+  }
+  if (options.retryFrom) {
+    argv.push("--retry-from", options.retryFrom);
+  }
+  if (options.pluginsRoot) {
+    argv.push("--plugins-root", options.pluginsRoot);
+  }
+  for (const path2 of options.pluginsPath ?? []) {
+    argv.push("--plugins-path", path2);
+  }
+  const code = await runFanout(argv);
+  if (code !== 0) {
+    throw new CommanderError(code, "kk.executor.fanout.failed", `fan-out failed with exit code ${code}`);
+  }
+}
+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-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("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);
 }
 
-// src/commands/plugins.ts
+// src/commands/plugin.ts
 import { existsSync as existsSync5 } from "fs";
 import { resolve as resolve5 } from "path";
-function registerPluginsCommand(program2) {
-  const pluginsCmd = program2.command("plugins").description("Manage and inspect knowledge-kit plugins");
-  pluginsCmd.command("list").description("List discovered plugins grouped by kind").option("--kind <kind>", "Filter plugins by kind (ingestion, generator, publish)").option("--json", "Output machine-readable JSON array").option("--plugins-root <dir>", "Root directory containing plugins").action((options) => {
-    const root = options.pluginsRoot ?? "./plugins";
-    const discovery = discoverPlugins(root);
-    let records = discovery.plugins;
-    if (options.kind) {
-      if (!isPluginKind(options.kind)) {
-        logger.error(`Invalid plugin kind: ${options.kind}
-`);
-        throw new CommanderError(1, "kk.plugins.invalid-kind", `invalid plugin kind: ${options.kind}`);
-      }
-      records = listByKind(discovery, options.kind);
+function collectPath2(value, acc) {
+  acc.push(value);
+  return acc;
+}
+function buildStatusReport(opts) {
+  const discovery = discoverAllPlugins({ pluginsRoot: opts.pluginsRoot, extraPaths: opts.pluginsPath });
+  const plugins = discovery.plugins.map((record2) => {
+    const diagnostics = [];
+    const entryPath = resolve5(record2.dir, record2.entry);
+    if (!existsSync5(entryPath)) {
+      diagnostics.push({
+        code: "missing_entry",
+        path: entryPath,
+        reason: `Plugin "${record2.name}" entry file does not exist: ${record2.entry}`
+      });
     }
-    if (options.json) {
-      logger.out(`${JSON.stringify(records, null, 2)}
+    return { ...record2, healthy: diagnostics.length === 0, diagnostics };
+  });
+  return {
+    healthy: discovery.diagnostics.length === 0 && plugins.every((p) => p.healthy),
+    plugins,
+    diagnostics: [...discovery.diagnostics]
+  };
+}
+function printDiagnostics(report) {
+  const all = [...report.diagnostics];
+  for (const p of report.plugins) {
+    all.push(...p.diagnostics);
+  }
+  logger.error(`Found ${all.length} diagnostic issue(s):
 `);
-      return;
-    }
-    if (records.length === 0) {
-      logger.out(`No plugins found.
+  for (const d of all) {
+    logger.error(`  [${d.code}] ${d.path}: ${d.reason}
 `);
-      return;
-    }
-    const kinds = options.kind ? [options.kind] : ["ingestion", "generator", "publish"];
-    for (const k of kinds) {
-      const group = records.filter((p) => p.kind === k);
-      if (group.length === 0)
-        continue;
-      logger.out(`
---- ${k.toUpperCase()} PLUGINS ---
+  }
+}
+function statusAction(options) {
+  if (options.pluginsRoot !== undefined && (options.pluginsPath?.length ?? 0) > 0) {
+    logger.error(`--plugins-root and --plugins-path are mutually exclusive (ADR-012 R6)
 `);
-      for (const p of group) {
-        const ver = p.version ? ` (v${p.version})` : "";
-        const desc = p.description ? ` - ${p.description}` : "";
-        logger.out(`  \u2022 ${p.name}${ver}: ${p.entry}${desc}
+    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)) {
+      logger.error(`Invalid plugin kind: ${options.kind}
 `);
-      }
-    }
-  });
-  pluginsCmd.command("doctor").description("Validate plugin manifests and entries under plugins root").option("--json", "Output machine-readable JSON object").option("--plugins-root <dir>", "Root directory containing plugins").action((options) => {
-    const root = options.pluginsRoot ?? "./plugins";
-    const discovery = discoverPlugins(root);
-    const diagnostics = [...discovery.diagnostics];
-    for (const p of discovery.plugins) {
-      const entryPath = resolve5(p.dir, p.entry);
-      if (!existsSync5(entryPath)) {
-        diagnostics.push({
-          code: "missing_entry",
-          path: entryPath,
-          reason: `Plugin "${p.name}" entry file does not exist: ${p.entry}`
-        });
-      }
+      throw new CommanderError(1, "kk.plugin.invalid-kind", `invalid plugin kind: ${options.kind}`);
     }
-    const healthy = diagnostics.length === 0;
-    if (options.json) {
-      logger.out(`${JSON.stringify({ healthy, diagnostics }, null, 2)}
+    records = report.plugins.filter((p) => p.kind === options.kind);
+  }
+  if (options.json) {
+    logger.out(`${JSON.stringify({ ...report, plugins: records }, null, 2)}
 `);
-      if (!healthy) {
-        throw new CommanderError(1, "kk.plugins.unhealthy", "plugin diagnostics found");
-      }
-      return;
+    if (!report.healthy) {
+      throw new CommanderError(1, "kk.plugin.unhealthy", "plugin diagnostics found");
     }
-    if (healthy) {
-      logger.out(`All plugin manifests and entries are healthy.
+    return;
+  }
+  if (records.length === 0) {
+    logger.out(`No plugins found.
 `);
-      return;
+    if (!report.healthy) {
+      printDiagnostics(report);
+      throw new CommanderError(1, "kk.plugin.unhealthy", "plugin diagnostics found");
     }
-    logger.error(`Found ${diagnostics.length} diagnostic issue(s):
+    return;
+  }
+  const kinds = options.kind ? [options.kind] : ["ingestion", "generator", "publish"];
+  for (const k of kinds) {
+    const group = records.filter((p) => p.kind === k);
+    if (group.length === 0)
+      continue;
+    logger.out(`
+--- ${k.toUpperCase()} PLUGINS ---
 `);
-    for (const d of diagnostics) {
-      logger.error(`  [${d.code}] ${d.path}: ${d.reason}
+    for (const p of group) {
+      const ver = p.version ? ` (v${p.version})` : "";
+      const desc = p.description ? ` - ${p.description}` : "";
+      const health = p.healthy ? "healthy" : "unhealthy";
+      logger.out(`  \u2022 ${p.name}${ver}: ${p.entry}${desc} [${health}]
 `);
     }
-    throw new CommanderError(1, "kk.plugins.unhealthy", "plugin diagnostics found");
-  });
+  }
+  if (!report.healthy) {
+    printDiagnostics(report);
+    throw new CommanderError(1, "kk.plugin.unhealthy", "plugin diagnostics found");
+  }
+}
+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);
+}
+function registerPluginCommand(program2) {
+  const plugin = program2.command("plugin").description("Inspect and validate knowledge-kit plugins");
+  registerStatusVerb(plugin, "status", "List discovered plugins grouped by kind with a per-plugin health mark", false);
+  registerStatusVerb(plugin, "list", "Alias for `plugin status` (deprecated)", true);
+  registerStatusVerb(plugin, "doctor", "Alias for `plugin status` (deprecated)", true);
+  const plugins = program2.command("plugins", { hidden: true }).description("Alias for `plugin status` (deprecated)");
+  registerStatusVerb(plugins, "status", "Alias for `plugin status` (deprecated)", true);
+  registerStatusVerb(plugins, "list", "Alias for `plugin status` (deprecated)", true);
+  registerStatusVerb(plugins, "doctor", "Alias for `plugin status` (deprecated)", true);
 }
 
 // src/config.ts
 import { readFileSync as readFileSync5 } from "fs";
-import { fileURLToPath } from "url";
-var pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+import { fileURLToPath as fileURLToPath2 } from "url";
+var pkgPath = fileURLToPath2(new URL("../package.json", import.meta.url));
 var pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
 var CLI_CONFIG = {
   binaryName: "kk",
@@ -17282,11 +17432,8 @@ var CLI_CONFIG = {
 // src/cli.ts
 function createProgram() {
   const program2 = new Command().name(CLI_CONFIG.binaryName).description("knowledge-kit CLI").version(CLI_CONFIG.binaryVersion).option("-v, --verbose", "enable verbose diagnostics");
-  registerAddCommand(program2);
-  registerInvokeCommand(program2);
-  registerFaninCommand(program2);
-  registerFanoutCommand(program2);
-  registerPluginsCommand(program2);
+  registerExecutorCommand(program2);
+  registerPluginCommand(program2);
   return program2;
 }
 

package/package.json

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

package/plugins/ingestions/web-search/package.json

@@ -0,0 +1,14 @@
+{
+    "name": "@gobing-ai/web-search",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@gobing-ai/kk-core": "workspace:*"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    }
+}

package/plugins/ingestions/web-search/plugin.json

@@ -0,0 +1,7 @@
+{
+    "name": "web-search",
+    "kind": "ingestion",
+    "entry": "./src/index.ts",
+    "version": "1.0.0",
+    "description": "Ingests web search results for a topic into Doc objects (fixture stub — no live Firecrawl in v1)"
+}

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

@@ -0,0 +1,144 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { type Doc, DocListSchema } from '@gobing-ai/kk-core';
+
+/** Validated `--in` input per the 0054 contract (`topic` required; `maxResults`/`fixture` optional). */
+interface InInput {
+    topic: string;
+    maxResults: number;
+    fixture: boolean;
+}
+
+/** Canned web-search results — the v1 fixture stub. Stable sourceUris → stable Doc ids. */
+interface FixtureEntry {
+    sourceUri: string;
+    title: string;
+    body: string;
+    position: number;
+}
+
+const FIXTURE_ENTRIES: FixtureEntry[] = [
+    {
+        sourceUri: 'https://example.org/research/storm-overview',
+        title: 'STORM: Topic Research via Composed Plugins — Overview',
+        body: '# STORM Overview\n\nSTORM chains ingestion and generation plugins over a single research topic.\n\n- **Ingest**: a web-search plugin materializes a `topic` into `Doc[]`\n- **Generate**: a generator plugin (content-gen) turns the `Doc[]` into grounded Content\n\nThis is fixture content emitted by the `web-search` v1 stub; no live Firecrawl call is made.',
+        position: 1,
+    },
+    {
+        sourceUri: 'https://example.org/research/storm-contract',
+        title: 'The web-search Ingest Contract (0054)',
+        body: '# Ingest Contract\n\nThe web-search `--in` JSON carries `topic` (required, non-empty string), `maxResults` (optional positive integer, default 8), and `fixture` (optional boolean, reserved for the stub).\n\nDoc `id` is the sha256 hex prefix (16 chars) of the canonical `sourceUri`, keeping ids deterministic across re-runs.',
+        position: 2,
+    },
+    {
+        sourceUri: 'https://example.org/research/storm-dry-run',
+        title: 'Dry-Running kk-storm-research',
+        body: '# Dry-Run\n\nThe `kk-storm-research` state machine materializes the topic `--vars` into the ingest `--in` JSON, runs `web-search`, then `content-gen`, and terminates at the Content-written `done` state — no publish.',
+        position: 3,
+    },
+];
+
+/** Deterministic Doc id: sha256(sourceUri) hex prefix, same idea as karakeep-local (0054 Block 4). */
+function computeId(uri: string): string {
+    return createHash('sha256').update(uri).digest('hex').slice(0, 16);
+}
+
+/**
+ * Build the fixture `Doc[]` for a topic (0054 Block 4 mapping). Always emits
+ * canned docs — the v1 plugin has no live Firecrawl path.
+ */
+export function buildFixtureDocs(topic: string, maxResults: number): Doc[] {
+    // maxResults caps the list per 0054 (cap semantics); `maxResults: 1` deliberately yields a
+    // single Doc. The Design's "always ≥2 items" wording applies to the default path (maxResults ≥ 2 → 3 canned entries).
+    const entries = FIXTURE_ENTRIES.slice(0, Math.max(0, Math.min(FIXTURE_ENTRIES.length, maxResults)));
+    return entries.map((entry, rank) => ({
+        id: computeId(entry.sourceUri),
+        body: entry.body,
+        title: entry.title,
+        sourceUri: entry.sourceUri,
+        mediaType: 'text/markdown',
+        metadata: {
+            query: topic,
+            rank,
+            position: entry.position,
+            // Per-run timestamp by design (0054 Block 4): determinism is required only for `id`.
+            scraped_at: new Date().toISOString(),
+        },
+    }));
+}
+
+/** Parse and validate the `--in` JSON; missing/invalid topic → throws (fail-loud row 1). */
+export function parseInput(raw: string): InInput {
+    let data: unknown;
+    try {
+        data = JSON.parse(raw);
+    } catch {
+        throw new Error('--in is not valid JSON');
+    }
+    if (typeof data !== 'object' || data === null) {
+        throw new Error('--in must be a JSON object');
+    }
+    const input = data as Record<string, unknown>;
+    if (typeof input.topic !== 'string' || input.topic.trim() === '') {
+        throw new Error('--in "topic" is required and must be a non-empty string');
+    }
+    let maxResults = 8;
+    if (input.maxResults !== undefined) {
+        if (typeof input.maxResults !== 'number' || !Number.isInteger(input.maxResults) || input.maxResults <= 0) {
+            throw new Error('--in "maxResults" must be a positive integer when present');
+        }
+        maxResults = input.maxResults;
+    }
+    return { topic: input.topic, maxResults, fixture: input.fixture === true };
+}
+
+export async function main(): Promise<number> {
+    const { values } = parseArgs({
+        options: {
+            in: { type: 'string' },
+            out: { type: 'string' },
+        },
+    });
+
+    if (!values.in || !values.out) {
+        console.error('Error: Missing required arguments --in and --out');
+        return 1;
+    }
+
+    let input: InInput;
+    try {
+        input = parseInput(await readFile(values.in, 'utf-8'));
+    } catch (err: unknown) {
+        console.error(`web-search failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+
+    if (!input.fixture) {
+        // 0054 Block 1/Block 8: `fixture` absent or false selects the LIVE Firecrawl path; v1 has no
+        // live client. Fail loud (Block 5 row-2 semantics: exit 1, no --out) instead of silently
+        // fabricating research docs — an obvious failure beats a surprising recovery.
+        console.error(
+            'web-search failed: live Firecrawl not implemented in v1 (pass "fixture": true to use the fixture stub)',
+        );
+        return 1;
+    }
+
+    try {
+        const docs = DocListSchema.parse(buildFixtureDocs(input.topic, input.maxResults));
+        const outDir = dirname(values.out);
+        if (outDir && outDir !== '.') {
+            await mkdir(outDir, { recursive: true });
+        }
+        await writeFile(values.out, JSON.stringify(docs, null, 2), 'utf-8');
+        return 0;
+    } catch (err: unknown) {
+        console.error(`web-search failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}

package/plugins/ingestions/web-search/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "include": ["src", "tests"]
+}

package/plugins/kk/skills/kk-judge/SKILL.md

@@ -60,7 +60,7 @@ Every evaluation writes a JSON verdict file. The default path is
 ## Evaluation procedure
 
 1. **Read the Content** from the path given in the evaluation request (the `content.json` written
-   by the preceding `kk invoke <generator>` step).
+   by the preceding `kk executor run <generator>` step).
 2. **Select the rubric** — either named in the request (`tech-accuracy`, `brand-tone`,
    `compliance`, `general`) or loaded by a thin wrapper. Default: `general`.
 3. **Evaluate each criterion** in the rubric. For each, produce a `pass` / `fail` / `warn` status

package/plugins/kk/skills/kk-topic/SKILL.md

@@ -31,7 +31,7 @@ Research, illustration, platform adaptation, and publishing are deliberately **o
 
 Do **not** use this skill for: materials extraction or research, image generation, platform
 adaptation, publishing, style-profile infrastructure, or anything requiring a runtime
-plugin (`kk invoke`, `plugin.json`, `GeneratorInput → Content`).
+plugin (`kk executor run`, `plugin.json`, `GeneratorInput → Content`).
 
 ## Invocation contract