@gobing-ai/knowledge-kit 0.0.17 → 0.0.19

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -0,0 +1,74 @@
+# @gobing-ai/knowledge-kit
+
+**Ingest → Create → Publish** — a content pipeline CLI. `knowledge-kit` turns documents (or
+just a topic brief) into finished, published content across multiple channels.
+
+> **The name is historical.** knowledge-kit is not only a knowledge-management tool: content
+> creation and multi-channel publishing are first-class, co-equal capabilities, and
+> **ingestion is optional** — a pipeline may start from a `Brief` (topic → article) with no
+> ingested documents.
+
+The binary installs as both `kk` and `knowledge-kit`. Pipelines are expressed as **plugins**
+(ingestion / generator / publish) wired together by [spur](https://www.npmjs.com/package/@gobing-ai/spur)
+workflows — `kk` owns each step, `spur` owns the orchestration.
+
+## Install
+
+```bash
+bun add -g @gobing-ai/knowledge-kit
+```
+
+Requires [Bun](https://bun.sh) ≥ 1.3.14.
+
+### Optional: install the `kk` agent plugin collection
+
+The npm tarball ships the `kk` plugin collection (skills, commands, agents, hooks, rules) for
+coding agents. Install it globally via [superskill](https://www.npmjs.com/package/@gobing-ai/superskill):
+
+```bash
+bun add -g @gobing-ai/superskill
+superskill install kk --marketplace gobing-ai/knowledge-kit
+```
+
+The repo is private, so superskill needs a GitHub token in the environment
+(`GITHUB_TOKEN` or `GH_TOKEN`). It caches under `~/.cache/superskill/marketplaces`
+(a warm cache works offline).
+
+## Commands
+
+| Command                                             | What it does                                                                        |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `kk executor run <plugin> --in <path> --out <path>` | Invoke a plugin with input/output files and contract validation                     |
+| `kk executor fan-in`                                | Merge N `Doc[]` JSON inputs into one deduplicated `Doc[]` output                    |
+| `kk executor fan-out`                               | Publish one `Content` JSON to N targets, aggregating per-target results             |
+| `kk plugin status`                                  | List discovered plugins grouped by kind with per-plugin health (`--kind`, `--json`) |
+| `kk -v, --verbose`                                  | Enable verbose diagnostics                                                          |
+| `kk --help` / `kk <command> --help`                 | Full flag reference                                                                 |
+
+Hidden one-release aliases (`invoke`, `fanin`, `fanout`, `plugins list`, `plugins doctor`)
+still work but are not listed in `kk --help`.
+
+## The plugin model
+
+Plugins are directories with a `plugin.json` manifest, discovered by a registry scan across
+built-in, user, project, and `KK_PLUGIN_PATH` roots. Three kinds:
+
+| Kind        | Contract                   | Shipped examples                                                 |
+| ----------- | -------------------------- | ---------------------------------------------------------------- |
+| `ingestion` | `source → Doc[]`           | `karakeep-local`, `web-search`, `last30days-ingest`              |
+| `generator` | `Doc[] \| Brief → Content` | `content-gen` (owned STORM pipeline), `voice-gen` (Voicebox TTS) |
+| `publish`   | `Content → Result`         | `surfdash-pub`, `zenn-pub`, `qiita-pub`                          |
+
+Core contracts (`Doc`, `Brief`, `Content`, `Result`) and per-kind validation live in
+`@gobing-ai/kk-core`. **LLM-as-judge is not a plugin kind** — quality gating is delivered as
+agent skills + `agent.run` in the `kk` plugin collection.
+
+## Documentation
+
+Source repo: [gobing-ai/knowledge-kit](https://github.com/gobing-ai/knowledge-kit) —
+architecture decisions (`docs/00_ADR.md`), command surface (`docs/04_DESIGN.md`), feature
+status (`docs/05_FEATURES.md`), and per-kind plugin authoring specs (`docs/design/`).
+
+## License
+
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0)

package/dist/index.js

@@ -14643,75 +14643,6 @@ var init_zod = __esm(() => {
   init_external();
 });
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.4.39/node_modules/@gobing-ai/ts-utils/dist/errors.js
-var ErrorCode;
-var init_errors3 = __esm(() => {
-  ErrorCode = {
-    NotFound: "NOT_FOUND",
-    Validation: "VALIDATION",
-    Conflict: "CONFLICT",
-    Internal: "INTERNAL"
-  };
-});
-
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.4.39/node_modules/@gobing-ai/ts-utils/dist/api-response.js
-var API_ERROR_CODES, ERROR_CODE_TO_HTTP, CLIENT_SAFE_CODES;
-var init_api_response = __esm(() => {
-  init_errors3();
-  API_ERROR_CODES = {
-    SUCCESS: 0,
-    NOT_FOUND: 404,
-    VALIDATION_ERROR: 422,
-    BAD_REQUEST: 400,
-    UNAUTHORIZED: 401,
-    FORBIDDEN: 403,
-    CONFLICT: 409,
-    INTERNAL_ERROR: 500
-  };
-  ERROR_CODE_TO_HTTP = {
-    [ErrorCode.NotFound]: API_ERROR_CODES.NOT_FOUND,
-    [ErrorCode.Validation]: API_ERROR_CODES.VALIDATION_ERROR,
-    [ErrorCode.Conflict]: API_ERROR_CODES.CONFLICT,
-    [ErrorCode.Internal]: API_ERROR_CODES.INTERNAL_ERROR
-  };
-  CLIENT_SAFE_CODES = new Set([ErrorCode.NotFound, ErrorCode.Validation, ErrorCode.Conflict]);
-});
-
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.4.39/node_modules/@gobing-ai/ts-utils/dist/cursor.js
-var init_cursor = () => {};
-
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.4.39/node_modules/@gobing-ai/ts-utils/dist/event-severity.js
-var init_event_severity = () => {};
-
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.4.39/node_modules/@gobing-ai/ts-utils/dist/output.js
-function processStream(name) {
-  const proc = globalThis.process;
-  const stream = proc?.[name];
-  if (stream === undefined) {
-    throw new Error(`No ${name} target available: set one via setDefaultOutputTargets or pass an explicit target`);
-  }
-  return stream;
-}
-function writeLine(message, target) {
-  target.write(`${message}
-`);
-}
-function echo(message, target = defaultStdoutTarget ?? processStream("stdout")) {
-  writeLine(message, target);
-}
-function echoError(message, target = defaultStderrTarget ?? processStream("stderr")) {
-  writeLine(message, target);
-}
-var defaultStdoutTarget, defaultStderrTarget;
-
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.4.39/node_modules/@gobing-ai/ts-utils/dist/index.js
-var init_dist = __esm(() => {
-  init_api_response();
-  init_cursor();
-  init_errors3();
-  init_event_severity();
-});
-
 // ../../node_modules/.bun/yaml@2.9.0/node_modules/yaml/dist/nodes/identity.js
 var require_identity = __commonJS((exports) => {
   var ALIAS = Symbol.for("yaml.alias");
@@ -17616,15 +17547,15 @@ var require_timestamp = __commonJS((exports) => {
         throw new Error("!!timestamp expects a date, starting with yyyy-mm-dd");
       const [, year, month, day, hour, minute, second] = match.map(Number);
       const millisec = match[7] ? Number((match[7] + "00").substr(1, 3)) : 0;
-      let date6 = Date.UTC(year, month - 1, day, hour || 0, minute || 0, second || 0, millisec);
+      let date5 = Date.UTC(year, month - 1, day, hour || 0, minute || 0, second || 0, millisec);
       const tz = match[8];
       if (tz && tz !== "Z") {
         let d = parseSexagesimal(tz, false);
         if (Math.abs(d) < 30)
           d *= 60;
-        date6 -= 60000 * d;
+        date5 -= 60000 * d;
       }
-      return new Date(date6);
+      return new Date(date5);
     },
     stringify: ({ value }) => value?.toISOString().replace(/(T00:00:00)?\.000Z$/, "") ?? ""
   };
@@ -19484,7 +19415,7 @@ var require_composer = __commonJS((exports) => {
   var node_process = __require("process");
   var directives = require_directives();
   var Document = require_Document();
-  var errors4 = require_errors();
+  var errors3 = require_errors();
   var identity = require_identity();
   var composeDoc = require_compose_doc();
   var resolveEnd = require_resolve_end();
@@ -19535,9 +19466,9 @@ var require_composer = __commonJS((exports) => {
       this.onError = (source, code, message, warning) => {
         const pos = getErrorPos(source);
         if (warning)
-          this.warnings.push(new errors4.YAMLWarning(pos, code, message));
+          this.warnings.push(new errors3.YAMLWarning(pos, code, message));
         else
-          this.errors.push(new errors4.YAMLParseError(pos, code, message));
+          this.errors.push(new errors3.YAMLParseError(pos, code, message));
       };
       this.directives = new directives.Directives({ version: options.version || "1.2" });
       this.options = options;
@@ -19623,7 +19554,7 @@ ${cb}` : comment;
           break;
         case "error": {
           const msg = token.source ? `${token.message}: ${JSON.stringify(token.source)}` : token.message;
-          const error51 = new errors4.YAMLParseError(getErrorPos(token), "UNEXPECTED_TOKEN", msg);
+          const error51 = new errors3.YAMLParseError(getErrorPos(token), "UNEXPECTED_TOKEN", msg);
           if (this.atDirectives || !this.doc)
             this.errors.push(error51);
           else
@@ -19633,7 +19564,7 @@ ${cb}` : comment;
         case "doc-end": {
           if (!this.doc) {
             const msg = "Unexpected doc-end without preceding document";
-            this.errors.push(new errors4.YAMLParseError(getErrorPos(token), "UNEXPECTED_TOKEN", msg));
+            this.errors.push(new errors3.YAMLParseError(getErrorPos(token), "UNEXPECTED_TOKEN", msg));
             break;
           }
           this.doc.directives.docEnd = true;
@@ -19648,7 +19579,7 @@ ${end.comment}` : end.comment;
           break;
         }
         default:
-          this.errors.push(new errors4.YAMLParseError(getErrorPos(token), "UNEXPECTED_TOKEN", `Unsupported token ${token.type}`));
+          this.errors.push(new errors3.YAMLParseError(getErrorPos(token), "UNEXPECTED_TOKEN", `Unsupported token ${token.type}`));
       }
     }
     *end(forceDoc = false, endOffset = -1) {
@@ -19674,7 +19605,7 @@ ${end.comment}` : end.comment;
 var require_cst_scalar = __commonJS((exports) => {
   var resolveBlockScalar = require_resolve_block_scalar();
   var resolveFlowScalar = require_resolve_flow_scalar();
-  var errors4 = require_errors();
+  var errors3 = require_errors();
   var stringifyString = require_stringifyString();
   function resolveAsScalar(token, strict = true, onError) {
     if (token) {
@@ -19683,7 +19614,7 @@ var require_cst_scalar = __commonJS((exports) => {
         if (onError)
           onError(offset, code, message);
         else
-          throw new errors4.YAMLParseError([offset, offset + 1], code, message);
+          throw new errors3.YAMLParseError([offset, offset + 1], code, message);
       };
       switch (token.type) {
         case "scalar":
@@ -21563,7 +21494,7 @@ var require_parser = __commonJS((exports) => {
 var require_public_api = __commonJS((exports) => {
   var composer = require_composer();
   var Document = require_Document();
-  var errors4 = require_errors();
+  var errors3 = require_errors();
   var log = require_log();
   var identity = require_identity();
   var lineCounter = require_line_counter();
@@ -21580,8 +21511,8 @@ var require_public_api = __commonJS((exports) => {
     const docs = Array.from(composer$1.compose(parser$1.parse(source)));
     if (prettyErrors && lineCounter2)
       for (const doc2 of docs) {
-        doc2.errors.forEach(errors4.prettifyError(source, lineCounter2));
-        doc2.warnings.forEach(errors4.prettifyError(source, lineCounter2));
+        doc2.errors.forEach(errors3.prettifyError(source, lineCounter2));
+        doc2.warnings.forEach(errors3.prettifyError(source, lineCounter2));
       }
     if (docs.length > 0)
       return docs;
@@ -21596,13 +21527,13 @@ var require_public_api = __commonJS((exports) => {
       if (!doc2)
         doc2 = _doc;
       else if (doc2.options.logLevel !== "silent") {
-        doc2.errors.push(new errors4.YAMLParseError(_doc.range.slice(0, 2), "MULTIPLE_DOCS", "Source contains multiple documents; please use YAML.parseAllDocuments()"));
+        doc2.errors.push(new errors3.YAMLParseError(_doc.range.slice(0, 2), "MULTIPLE_DOCS", "Source contains multiple documents; please use YAML.parseAllDocuments()"));
         break;
       }
     }
     if (prettyErrors && lineCounter2) {
-      doc2.errors.forEach(errors4.prettifyError(source, lineCounter2));
-      doc2.warnings.forEach(errors4.prettifyError(source, lineCounter2));
+      doc2.errors.forEach(errors3.prettifyError(source, lineCounter2));
+      doc2.warnings.forEach(errors3.prettifyError(source, lineCounter2));
     }
     return doc2;
   }
@@ -21654,12 +21585,12 @@ var require_public_api = __commonJS((exports) => {
 });
 
 // ../../node_modules/.bun/yaml@2.9.0/node_modules/yaml/dist/index.js
-var composer, Document, Schema, errors4, Alias, identity, Pair, Scalar, YAMLMap, YAMLSeq, cst, lexer, lineCounter, parser, publicApi, visit, $Composer, $Document, $Schema, $YAMLError, $YAMLParseError, $YAMLWarning, $Alias, $isAlias, $isCollection, $isDocument, $isMap, $isNode, $isPair, $isScalar, $isSeq, $Pair, $Scalar, $YAMLMap, $YAMLSeq, $Lexer, $LineCounter, $Parser, $parse, $parseAllDocuments, $parseDocument, $stringify, $visit, $visitAsync;
-var init_dist2 = __esm(() => {
+var composer, Document, Schema, errors3, Alias, identity, Pair, Scalar, YAMLMap, YAMLSeq, cst, lexer, lineCounter, parser, publicApi, visit, $Composer, $Document, $Schema, $YAMLError, $YAMLParseError, $YAMLWarning, $Alias, $isAlias, $isCollection, $isDocument, $isMap, $isNode, $isPair, $isScalar, $isSeq, $Pair, $Scalar, $YAMLMap, $YAMLSeq, $Lexer, $LineCounter, $Parser, $parse, $parseAllDocuments, $parseDocument, $stringify, $visit, $visitAsync;
+var init_dist = __esm(() => {
   composer = require_composer();
   Document = require_Document();
   Schema = require_Schema();
-  errors4 = require_errors();
+  errors3 = require_errors();
   Alias = require_Alias();
   identity = require_identity();
   Pair = require_Pair();
@@ -21675,9 +21606,9 @@ var init_dist2 = __esm(() => {
   $Composer = composer.Composer;
   $Document = Document.Document;
   $Schema = Schema.Schema;
-  $YAMLError = errors4.YAMLError;
-  $YAMLParseError = errors4.YAMLParseError;
-  $YAMLWarning = errors4.YAMLWarning;
+  $YAMLError = errors3.YAMLError;
+  $YAMLParseError = errors3.YAMLParseError;
+  $YAMLWarning = errors3.YAMLWarning;
   $Alias = Alias.Alias;
   $isAlias = identity.isAlias;
   $isCollection = identity.isCollection;
@@ -21705,7 +21636,7 @@ var init_dist2 = __esm(() => {
 // ../../node_modules/.bun/@gobing-ai+ts-runtime@0.4.39/node_modules/@gobing-ai/ts-runtime/dist/config.js
 var configSchema;
 var init_config = __esm(() => {
-  init_dist2();
+  init_dist();
   init_zod();
   configSchema = exports_external.object({
     app: exports_external.object({
@@ -26385,16 +26316,34 @@ function getByName(result, name) {
 init_file_system_node();
 init_config();
 
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.4.67/node_modules/@gobing-ai/ts-utils/dist/output.js
+var defaultStdoutTarget;
+var defaultStderrTarget;
+function processStream(name) {
+  const proc = globalThis.process;
+  const stream = proc?.[name];
+  if (stream === undefined) {
+    throw new Error(`No ${name} target available: set one via setDefaultOutputTargets or pass an explicit target`);
+  }
+  return stream;
+}
+function writeLine(message, target) {
+  target.write(`${message}
+`);
+}
+function echo(message, target = defaultStdoutTarget ?? processStream("stdout")) {
+  writeLine(message, target);
+}
+function echoError(message, target = defaultStderrTarget ?? processStream("stderr")) {
+  writeLine(message, target);
+}
+
 // ../../packages/kk-core/src/render-md.ts
 if (false) {}
-// src/fanin.ts
-init_dist();
-
 // src/invoke.ts
 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";
-init_dist();
 function resolveKkConfigPath() {
   return process.env.KK_CONFIG || join2(homedir2(), ".config/kk/config.yaml");
 }
@@ -26471,24 +26420,38 @@ function spawnPluginEntry(opts) {
     stderr: proc.stderr.toString().trim()
   };
 }
-function killProcessTree(pid) {
+var KILL_TREE_SETTLE_MS = 100;
+function listChildren(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);
-    }
+  return stdout.trim().split(`
+`).map(Number).filter((child) => Number.isInteger(child) && child > 0);
+}
+function killSubtree(pid) {
+  for (const child of listChildren(pid)) {
+    killSubtree(child);
   }
   try {
     process.kill(pid, "SIGKILL");
   } catch {}
 }
+async function killProcessTree(pid) {
+  const sweep = () => {
+    for (const child of listChildren(pid)) {
+      killSubtree(child);
+    }
+  };
+  sweep();
+  await Bun.sleep(KILL_TREE_SETTLE_MS);
+  sweep();
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {}
+}
 async function spawnPluginEntryAsync(opts) {
   let timedOut = false;
   let timer;
@@ -26938,7 +26901,6 @@ async function runFanin(argv) {
 // 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) {
@@ -27378,10 +27340,8 @@ function registerExecutorCommand(program2) {
 // src/commands/plugin.ts
 import { existsSync as existsSync4 } from "fs";
 import { resolve as resolve5 } from "path";
-init_dist();
 
 // src/output.ts
-init_dist();
 function withoutFinalLineEnding(message) {
   return message.replace(/\r?\n$/, "");
 }
@@ -27499,6 +27459,46 @@ function registerPluginCommand(program2) {
   registerStatusVerb(plugins, "doctor", "Alias for `plugin status` (deprecated)", true);
 }
 
+// src/stage.ts
+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]) {
+  let fromPkg = "";
+  if (argv1) {
+    try {
+      fromPkg = join5(dirname3(dirname3(realpathSync3(argv1))), STAGES_REL);
+    } catch {
+      fromPkg = "";
+    }
+  }
+  if (fromPkg && existsSync5(fromPkg))
+    return fromPkg;
+  const fromCwd = resolve6(STAGES_REL);
+  if (existsSync5(fromCwd))
+    return fromCwd;
+  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) {
+  const script = resolveStagesScript(argv1);
+  const res = spawnSync(execPath, [script, ...args], { stdio: "inherit" });
+  if (res.error) {
+    throw new Error(`failed to spawn stage runner at ${script}: ${res.error.message}`);
+  }
+  return res.status ?? 1;
+}
+
+// src/commands/stage.ts
+function registerStageCommand(program2) {
+  program2.command("stage").description("Run a kk-workflow-stages.ts stage (workflow orchestration steps)").argument("<args...>", "Stage name followed by its positional arguments").allowUnknownOption(true).action((args) => {
+    const code = runStage(args);
+    if (code !== 0) {
+      throw new CommanderError(code, "kk.stage.failed", `stage failed with exit code ${code}`);
+    }
+  });
+}
+
 // src/config.ts
 import { readFileSync as readFileSync4 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -27514,6 +27514,7 @@ function createProgram() {
   const program2 = new Command().name(CLI_CONFIG.binaryName).description("knowledge-kit CLI").version(CLI_CONFIG.binaryVersion).option("-v, --verbose", "enable verbose diagnostics");
   registerExecutorCommand(program2);
   registerPluginCommand(program2);
+  registerStageCommand(program2);
   return program2;
 }
 

package/package.json

@@ -1,13 +1,31 @@
 {
     "name": "@gobing-ai/knowledge-kit",
-    "version": "0.0.17",
+    "version": "0.0.19",
     "description": "An ingest → create → publish content pipeline CLI (Bun).",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/gobing-ai/knowledge-kit.git"
     },
+    "homepage": "https://github.com/gobing-ai/knowledge-kit#readme",
+    "bugs": {
+        "url": "https://github.com/gobing-ai/knowledge-kit/issues"
+    },
+    "keywords": [
+        "cli",
+        "content-pipeline",
+        "content-creation",
+        "publishing",
+        "ingestion",
+        "plugins",
+        "ai",
+        "bun",
+        "typescript"
+    ],
     "author": "Robin Min <minlongbing@gmail.com>",
     "license": "Apache-2.0",
+    "engines": {
+        "bun": ">=1.3.14"
+    },
     "type": "module",
     "bin": {
         "kk": "./dist/index.js",