@kaddo/cli 3.125.0 → 3.126.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/core.js +205 -64
  2. package/dist/index.js +247 -98
  3. package/package.json +1 -1
package/dist/core.js CHANGED
@@ -15649,6 +15649,7 @@ import fs7 from "fs";
15649
15649
  import path6 from "path";
15650
15650
 
15651
15651
  // src/core/okf/mapping.ts
15652
+ import matter19 from "gray-matter";
15652
15653
  var OKF_TYPE_TABLE = {
15653
15654
  "business-knowledge": "Business Knowledge",
15654
15655
  "product-knowledge": "Product Knowledge",
@@ -15666,6 +15667,13 @@ var OKF_TYPE_TABLE = {
15666
15667
  };
15667
15668
  var WORK_ITEM_TYPES3 = /* @__PURE__ */ new Set(["feature", "bugfix", "hotfix", "spike", "chore"]);
15668
15669
  var REPORT_TYPES = /* @__PURE__ */ new Set(["impact-report", "drift-report", "savings-report", "poc-report"]);
15670
+ var AGENT_INSTRUCTION_TYPES = /* @__PURE__ */ new Set(["agent", "workflow", "prompt", "skill"]);
15671
+ function isAgentInstruction(a) {
15672
+ const t = (a.type || "").toLowerCase();
15673
+ if (AGENT_INSTRUCTION_TYPES.has(t)) return true;
15674
+ const p = a.relPath.toLowerCase();
15675
+ return p.includes("/agents/") || p.includes("/skills/") || p.includes("/workflows/");
15676
+ }
15669
15677
  function okfConceptType(a) {
15670
15678
  if (a.isWorkItem) return "Work Item";
15671
15679
  const t = (a.type || "").toLowerCase();
@@ -15688,6 +15696,7 @@ function conceptBundlePath(a, id) {
15688
15696
  const file = `${id}.md`;
15689
15697
  if (a.isWorkItem) return `delivery/work-items/${file}`;
15690
15698
  const t = (a.type || "").toLowerCase();
15699
+ if (isAgentInstruction(a)) return `agents/${file}`;
15691
15700
  if (t === "deprecation-plan") return `delivery/deprecations/${file}`;
15692
15701
  if (t === "production-runbook") return `delivery/runbooks/${file}`;
15693
15702
  if (t === "project-resource") return `resources/${file}`;
@@ -15739,6 +15748,14 @@ function conceptId(a) {
15739
15748
  const base = a.relPath.split("/").pop() ?? "";
15740
15749
  return slugify4(base.replace(/\.md$/, "")) || slugify4(a.relPath);
15741
15750
  }
15751
+ function readBody2(a) {
15752
+ try {
15753
+ const body = matter19(readFile(a.filePath)).content.trim();
15754
+ return body || null;
15755
+ } catch {
15756
+ return null;
15757
+ }
15758
+ }
15742
15759
  function buildConcept(a) {
15743
15760
  const id = conceptId(a);
15744
15761
  if (!id) return null;
@@ -15752,10 +15769,24 @@ function buildConcept(a) {
15752
15769
  path: conceptBundlePath(a, id),
15753
15770
  sourcePath: a.relPath,
15754
15771
  related: a.isWorkItem ? workItemRelations(rawFm) : [],
15755
- body: null
15772
+ // Preserve the canonical Markdown body so the concept is consumable, not just discoverable (WI-066 P1).
15773
+ body: readBody2(a)
15756
15774
  };
15757
15775
  }
15758
15776
 
15777
+ // src/core/okf/types.ts
15778
+ var OKF_VERSION = "0.2";
15779
+ var OKF_RESERVED_FILES = ["index.md", "log.md"];
15780
+ var OKF_EXPORT_PROCESS = "process:kaddo-okf-export";
15781
+ var OkfExportError = class extends Error {
15782
+ constructor(code, message) {
15783
+ super(message);
15784
+ this.code = code;
15785
+ this.name = "OkfExportError";
15786
+ }
15787
+ code;
15788
+ };
15789
+
15759
15790
  // src/core/okf/extras.ts
15760
15791
  function reportConcepts(dir, now = /* @__PURE__ */ new Date()) {
15761
15792
  const concepts = [];
@@ -15772,6 +15803,7 @@ function reportConcepts(dir, now = /* @__PURE__ */ new Date()) {
15772
15803
  tags: ["report"],
15773
15804
  path: `reports/${id}.md`,
15774
15805
  sourcePath: null,
15806
+ generatedBy: OKF_EXPORT_PROCESS,
15775
15807
  generatedAt: at,
15776
15808
  related: [],
15777
15809
  body
@@ -15826,10 +15858,6 @@ function externalCapsuleConcepts(dir) {
15826
15858
  });
15827
15859
  }
15828
15860
 
15829
- // src/core/okf/types.ts
15830
- var OKF_VERSION = "0.2";
15831
- var OKF_RESERVED_FILES = ["index.md", "log.md"];
15832
-
15833
15861
  // src/core/okf/export.ts
15834
15862
  var OKF_DEFAULT_OUTPUT = ".kaddo/okf";
15835
15863
  function frontmatter(data) {
@@ -15848,6 +15876,11 @@ function frontmatter(data) {
15848
15876
  lines.push(` - ${JSON.stringify(item)}`);
15849
15877
  }
15850
15878
  }
15879
+ } else if (v && typeof v === "object") {
15880
+ lines.push(`${k}:`);
15881
+ for (const [ik, iv] of Object.entries(v)) {
15882
+ if (iv != null) lines.push(` ${ik}: ${JSON.stringify(iv)}`);
15883
+ }
15851
15884
  } else {
15852
15885
  lines.push(`${k}: ${JSON.stringify(v)}`);
15853
15886
  }
@@ -15859,7 +15892,20 @@ function relLink(fromPath, toPath) {
15859
15892
  const rel = path6.posix.relative(path6.posix.dirname(fromPath), toPath);
15860
15893
  return rel.startsWith(".") ? rel : `./${rel}`;
15861
15894
  }
15862
- function renderConcept(c, byId) {
15895
+ function rewriteBodyLinks(body, sourcePath, srcToBundle, selfBundlePath) {
15896
+ const srcDir = path6.posix.dirname(sourcePath);
15897
+ return body.replace(/\]\(([^)]+)\)/g, (whole, href) => {
15898
+ const raw = href.trim();
15899
+ const bare = raw.split("#")[0].split(" ")[0];
15900
+ if (!bare || /^(https?:|mailto:|#)/.test(bare)) return whole;
15901
+ const candidate = bare.startsWith("/") ? bare.replace(/^\/+/, "") : path6.posix.normalize(path6.posix.join(srcDir, bare));
15902
+ const target = srcToBundle.get(candidate);
15903
+ if (!target) return whole;
15904
+ const anchor = raw.includes("#") ? "#" + raw.split("#").slice(1).join("#") : "";
15905
+ return `](${relLink(selfBundlePath, target)}${anchor})`;
15906
+ });
15907
+ }
15908
+ function renderConcept(c, byId, srcToBundle) {
15863
15909
  const data = {
15864
15910
  type: c.type,
15865
15911
  title: c.title,
@@ -15868,10 +15914,13 @@ function renderConcept(c, byId) {
15868
15914
  kaddo_id: c.id
15869
15915
  };
15870
15916
  if (c.sourcePath) data.sources = [{ resource: c.sourcePath }];
15871
- if (c.generatedAt) data.generated = { at: c.generatedAt };
15917
+ if (c.generatedBy || c.generatedAt) {
15918
+ data.generated = { ...c.generatedBy ? { by: c.generatedBy } : {}, ...c.generatedAt ? { at: c.generatedAt } : {} };
15919
+ }
15872
15920
  const parts = [frontmatter(data)];
15873
15921
  if (c.body) {
15874
- parts.push("", c.body.trim());
15922
+ const body = c.sourcePath ? rewriteBodyLinks(c.body, c.sourcePath, srcToBundle, c.path) : c.body;
15923
+ parts.push("", body.trim());
15875
15924
  } else {
15876
15925
  parts.push("", `# ${c.title}`);
15877
15926
  if (c.description) parts.push("", c.description);
@@ -15886,15 +15935,20 @@ function renderConcept(c, byId) {
15886
15935
  }
15887
15936
  return parts.join("\n") + "\n";
15888
15937
  }
15889
- function renderIndex(title, concepts, fromPath, root) {
15890
- const data = { type: "Index", title };
15891
- if (root) data.okf_version = OKF_VERSION;
15892
- const parts = [frontmatter(data), "", `# ${title}`, ""];
15938
+ function renderIndex(title, concepts, childDirs, fromPath, root) {
15939
+ const parts = [];
15940
+ if (root) parts.push(frontmatter({ okf_version: OKF_VERSION }), "");
15941
+ parts.push(`# ${title}`, "");
15893
15942
  if (root) parts.push(
15894
- `Open Knowledge Format bundle \u2014 version ${OKF_VERSION}. A portable projection of`,
15895
- "Kaddo knowledge. Kaddo remains the source of truth.",
15943
+ "Open Knowledge Format bundle \u2014 a portable projection of Kaddo knowledge.",
15944
+ "Kaddo remains the source of truth.",
15896
15945
  ""
15897
15946
  );
15947
+ if (childDirs.length > 0) {
15948
+ parts.push("## Sections");
15949
+ for (const d of [...childDirs].sort()) parts.push(`- [${d}/](${relLink(fromPath, `${d}/index.md`)})`);
15950
+ parts.push("");
15951
+ }
15898
15952
  const byType = /* @__PURE__ */ new Map();
15899
15953
  for (const c of concepts) {
15900
15954
  const l = byType.get(c.type) ?? [];
@@ -15904,84 +15958,168 @@ function renderIndex(title, concepts, fromPath, root) {
15904
15958
  for (const type of [...byType.keys()].sort()) {
15905
15959
  parts.push(`## ${type}`);
15906
15960
  for (const c of byType.get(type).sort((a, b) => a.id.localeCompare(b.id))) {
15907
- parts.push(`- [${c.title}](${relLink(fromPath, c.path)})`);
15961
+ const d = c.description ? ` \u2014 ${c.description}` : "";
15962
+ parts.push(`- [${c.title}](${relLink(fromPath, c.path)})${d}`);
15908
15963
  }
15909
15964
  parts.push("");
15910
15965
  }
15911
15966
  return parts.join("\n");
15912
15967
  }
15913
- function atomicWrite5(file, content) {
15914
- fs7.mkdirSync(path6.dirname(file), { recursive: true });
15915
- fs7.writeFileSync(file, content, "utf-8");
15916
- }
15917
15968
  var SENSITIVE_PATTERNS = [
15918
15969
  { re: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/, label: "private key block" },
15919
15970
  { re: /\bAKIA[0-9A-Z]{16}\b/, label: "AWS access key id" },
15920
15971
  { re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/, label: "GitHub token" },
15921
15972
  { re: /\b(?:password|secret|api[_-]?key|access[_-]?token)\b\s*[:=]\s*["']?[A-Za-z0-9+/_\-]{12,}/i, label: "inline credential" }
15922
15973
  ];
15923
- function scanSensitive(renderedPath, content) {
15924
- const hits = SENSITIVE_PATTERNS.filter((p) => p.re.test(content)).map((p) => p.label);
15925
- return hits.length > 0 ? [`${renderedPath}: possible ${[...new Set(hits)].join(", ")} \u2014 review before sharing.`] : [];
15974
+ function sensitiveLabels(content) {
15975
+ return [...new Set(SENSITIVE_PATTERNS.filter((p) => p.re.test(content)).map((p) => p.label))];
15976
+ }
15977
+ function assertSafeDestination(dir, outputDir) {
15978
+ const root = path6.resolve(dir);
15979
+ const out = path6.resolve(outputDir);
15980
+ const within = (child, parent) => {
15981
+ const rel = path6.relative(parent, child);
15982
+ return rel === "" || !rel.startsWith("..") && !path6.isAbsolute(rel);
15983
+ };
15984
+ if (out === root) throw new OkfExportError("UNSAFE_DESTINATION", "Refusing to export onto the project root.");
15985
+ if (within(root, out)) throw new OkfExportError("UNSAFE_DESTINATION", "Refusing to export onto a parent of the project.");
15986
+ for (const protectedDir of ["knowledge", "packages", "apps", "src", "node_modules", ".git"]) {
15987
+ const p = path6.join(root, protectedDir);
15988
+ if (out === p || within(out, p)) throw new OkfExportError("UNSAFE_DESTINATION", `Refusing to export into a protected directory: ${protectedDir}/`);
15989
+ }
15990
+ if (fs7.existsSync(out)) {
15991
+ try {
15992
+ const entries = fs7.readdirSync(out);
15993
+ const looksOkf = entries.includes("index.md") && /okf_version/.test(fs7.readFileSync(path6.join(out, "index.md"), "utf-8"));
15994
+ if (entries.length > 0 && !looksOkf) {
15995
+ throw new OkfExportError("UNSAFE_DESTINATION", `Destination is not empty and is not an OKF bundle: ${outputDir}. Use an empty or dedicated directory.`);
15996
+ }
15997
+ } catch (e) {
15998
+ if (e instanceof OkfExportError) throw e;
15999
+ }
16000
+ }
16001
+ }
16002
+ function detectCollisions(concepts) {
16003
+ const byId = /* @__PURE__ */ new Map();
16004
+ const byPath = /* @__PURE__ */ new Map();
16005
+ const errors = [];
16006
+ for (const c of concepts) {
16007
+ const prev = byId.get(c.id);
16008
+ if (prev && prev !== (c.sourcePath ?? "")) errors.push(`Concept id "${c.id}" is produced by two different sources: ${prev} and ${c.sourcePath}.`);
16009
+ else byId.set(c.id, c.sourcePath ?? "");
16010
+ const prevP = byPath.get(c.path);
16011
+ if (prevP && prevP !== c.id) errors.push(`Destination path "${c.path}" is claimed by two concepts: ${prevP} and ${c.id}.`);
16012
+ else byPath.set(c.path, c.id);
16013
+ }
16014
+ return errors;
15926
16015
  }
15927
16016
  function exportOkf(dir, opts = {}) {
15928
16017
  const outRel = opts.output ?? OKF_DEFAULT_OUTPUT;
15929
16018
  const outputDir = path6.isAbsolute(outRel) ? outRel : path6.join(dir, outRel);
16019
+ assertSafeDestination(dir, outputDir);
15930
16020
  const extraWarnings = [];
15931
16021
  const artifacts = discoverKnowledge(dir);
15932
- const concepts = [];
15933
- const seen = /* @__PURE__ */ new Set();
16022
+ const raw = [];
15934
16023
  const omittedCounts = /* @__PURE__ */ new Map();
15935
- const addConcept = (c) => {
15936
- if (!c || seen.has(c.id)) return;
15937
- seen.add(c.id);
15938
- concepts.push(c);
15939
- };
16024
+ const omittedConcepts = [];
16025
+ const bump = (type) => omittedCounts.set(type, (omittedCounts.get(type) ?? 0) + 1);
16026
+ const sameSource = /* @__PURE__ */ new Set();
15940
16027
  for (const a of artifacts) {
16028
+ if (isAgentInstruction(a) && !opts.withAgents) {
16029
+ bump(a.type || "agent");
16030
+ continue;
16031
+ }
15941
16032
  const c = buildConcept(a);
15942
16033
  if (!c) {
15943
- omittedCounts.set(a.type || "unknown", (omittedCounts.get(a.type || "unknown") ?? 0) + 1);
16034
+ bump(a.type || "unknown");
15944
16035
  continue;
15945
16036
  }
15946
- addConcept(c);
16037
+ const key = `${c.id}\0${c.sourcePath ?? ""}`;
16038
+ if (sameSource.has(key)) continue;
16039
+ sameSource.add(key);
16040
+ raw.push(c);
15947
16041
  }
15948
- for (const c of externalCapsuleConcepts(dir)) addConcept(c);
16042
+ for (const c of externalCapsuleConcepts(dir)) raw.push(c);
15949
16043
  if (opts.withReports) {
15950
- const { concepts: reports, warnings: warnings2 } = reportConcepts(dir, opts.now ?? /* @__PURE__ */ new Date());
15951
- for (const c of reports) addConcept(c);
15952
- extraWarnings.push(...warnings2);
16044
+ const { concepts: reports, warnings } = reportConcepts(dir, opts.now ?? /* @__PURE__ */ new Date());
16045
+ raw.push(...reports);
16046
+ extraWarnings.push(...warnings);
16047
+ }
16048
+ const collisions = detectCollisions(raw);
16049
+ if (collisions.length > 0) {
16050
+ throw new OkfExportError("IDENTITY_COLLISION", `Cannot export: ${collisions.length} unresolved identity collision(s):
16051
+ - ${collisions.join("\n- ")}`);
16052
+ }
16053
+ const concepts = [];
16054
+ for (const c of raw) {
16055
+ const hay = `${c.title}
16056
+ ${c.description ?? ""}
16057
+ ${c.body ?? ""}`;
16058
+ const labels = sensitiveLabels(hay);
16059
+ if (labels.length > 0) {
16060
+ omittedConcepts.push({ id: c.id, reason: `potential ${labels.join(", ")}` });
16061
+ continue;
16062
+ }
16063
+ concepts.push(c);
15953
16064
  }
15954
16065
  concepts.sort((a, b) => a.id.localeCompare(b.id));
15955
16066
  const byId = new Map(concepts.map((c) => [c.id, c]));
15956
- const layerOf = (p) => p.split("/")[0];
15957
- const byLayer = /* @__PURE__ */ new Map();
16067
+ const srcToBundle = /* @__PURE__ */ new Map();
16068
+ for (const c of concepts) if (c.sourcePath) srcToBundle.set(c.sourcePath, c.path);
16069
+ const files = /* @__PURE__ */ new Map();
16070
+ for (const c of concepts) files.set(c.path, renderConcept(c, byId, srcToBundle));
16071
+ const dirs = /* @__PURE__ */ new Map();
16072
+ const childDirs = /* @__PURE__ */ new Map();
15958
16073
  for (const c of concepts) {
15959
- const l = byLayer.get(layerOf(c.path)) ?? [];
15960
- l.push(c);
15961
- byLayer.set(layerOf(c.path), l);
16074
+ const d = path6.posix.dirname(c.path);
16075
+ (dirs.get(d) ?? dirs.set(d, []).get(d)).push(c);
16076
+ const segs = d === "." ? [] : d.split("/");
16077
+ for (let i = 0; i < segs.length; i++) {
16078
+ const parent = segs.slice(0, i).join("/") || ".";
16079
+ const child = segs.slice(0, i + 1).join("/");
16080
+ (childDirs.get(parent) ?? childDirs.set(parent, /* @__PURE__ */ new Set()).get(parent)).add(child);
16081
+ }
15962
16082
  }
15963
- fs7.rmSync(outputDir, { recursive: true, force: true });
15964
- fs7.mkdirSync(outputDir, { recursive: true });
15965
- const written = [];
15966
- const warnings = [];
15967
- const write = (bundlePath, content) => {
15968
- atomicWrite5(path6.join(outputDir, bundlePath), content);
15969
- written.push(bundlePath);
15970
- warnings.push(...scanSensitive(bundlePath, content));
15971
- };
15972
- for (const c of concepts) write(c.path, renderConcept(c, byId));
15973
- for (const layer of [...byLayer.keys()].sort()) {
15974
- const title = layer.charAt(0).toUpperCase() + layer.slice(1);
15975
- write(`${layer}/index.md`, renderIndex(`${title} Knowledge`, byLayer.get(layer), `${layer}/index.md`, false));
15976
- }
15977
- write("index.md", renderIndex("Knowledge bundle", concepts, "index.md", true));
15978
- written.sort();
16083
+ let indexCount = 0;
16084
+ for (const [d, cs] of dirs) {
16085
+ if (d === ".") continue;
16086
+ const title = d.split("/").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join(" / ");
16087
+ const kids = [...childDirs.get(d) ?? []].map((c) => c.split("/").pop());
16088
+ files.set(`${d}/index.md`, renderIndex(title, cs, kids, `${d}/index.md`, false));
16089
+ indexCount++;
16090
+ }
16091
+ const rootConcepts = dirs.get(".") ?? [];
16092
+ const rootKids = [...childDirs.get(".") ?? []];
16093
+ files.set("index.md", renderIndex("Knowledge bundle", rootConcepts, rootKids, "index.md", true));
16094
+ indexCount++;
16095
+ const staging = `${outputDir}.staging-${process.pid}-${Date.now()}`;
16096
+ try {
16097
+ fs7.rmSync(staging, { recursive: true, force: true });
16098
+ for (const [rel, content] of files) {
16099
+ const full = path6.join(staging, rel);
16100
+ fs7.mkdirSync(path6.dirname(full), { recursive: true });
16101
+ fs7.writeFileSync(full, content, "utf-8");
16102
+ }
16103
+ const backup = `${outputDir}.old-${process.pid}-${Date.now()}`;
16104
+ if (fs7.existsSync(outputDir)) fs7.renameSync(outputDir, backup);
16105
+ try {
16106
+ fs7.renameSync(staging, outputDir);
16107
+ } catch (e) {
16108
+ if (fs7.existsSync(backup)) fs7.renameSync(backup, outputDir);
16109
+ throw e;
16110
+ }
16111
+ fs7.rmSync(backup, { recursive: true, force: true });
16112
+ } finally {
16113
+ fs7.rmSync(staging, { recursive: true, force: true });
16114
+ }
16115
+ const written = [...files.keys()].sort();
15979
16116
  return {
15980
16117
  outputDir,
15981
16118
  conceptCount: concepts.length,
15982
- indexCount: byLayer.size + 1,
16119
+ indexCount,
15983
16120
  omitted: [...omittedCounts.entries()].map(([type, count]) => ({ type, count })).sort((a, b) => a.type.localeCompare(b.type)),
15984
- warnings: [...warnings, ...extraWarnings].sort(),
16121
+ omittedConcepts: omittedConcepts.sort((a, b) => a.id.localeCompare(b.id)),
16122
+ warnings: extraWarnings.sort(),
15985
16123
  files: written
15986
16124
  };
15987
16125
  }
@@ -15989,7 +16127,7 @@ function exportOkf(dir, opts = {}) {
15989
16127
  // src/core/okf/validate.ts
15990
16128
  import fs8 from "fs";
15991
16129
  import path7 from "path";
15992
- import matter19 from "gray-matter";
16130
+ import matter20 from "gray-matter";
15993
16131
  function walk(root) {
15994
16132
  const out = [];
15995
16133
  const rec = (d) => {
@@ -16036,16 +16174,16 @@ function validateOkf(dir, opts = {}) {
16036
16174
  const isIndex = path7.basename(file) === "index.md";
16037
16175
  let data = {};
16038
16176
  try {
16039
- data = matter19(fs8.readFileSync(file, "utf-8")).data ?? {};
16177
+ data = matter20(fs8.readFileSync(file, "utf-8")).data ?? {};
16040
16178
  } catch {
16041
16179
  findings.push({ level: "conformance", file: r, message: "Invalid YAML frontmatter." });
16042
16180
  continue;
16043
16181
  }
16044
16182
  const type = typeof data.type === "string" ? data.type.trim() : "";
16045
- if (!type) {
16046
- findings.push(isIndex ? { level: "warning", file: r, message: "Index has no type." } : { level: "conformance", file: r, message: "Concept has no non-empty `type`." });
16183
+ if (!isIndex) {
16184
+ if (!type) findings.push({ level: "conformance", file: r, message: "Concept has no non-empty `type`." });
16185
+ conceptCount++;
16047
16186
  }
16048
- if (!isIndex) conceptCount++;
16049
16187
  if (r === "index.md") {
16050
16188
  const v = typeof data.okf_version === "string" ? data.okf_version : data.okf_version != null ? String(data.okf_version) : "";
16051
16189
  if (!v) findings.push({ level: "warning", file: r, message: "Root index does not declare okf_version." });
@@ -16058,7 +16196,7 @@ function validateOkf(dir, opts = {}) {
16058
16196
  }
16059
16197
  const body = (() => {
16060
16198
  try {
16061
- return matter19(fs8.readFileSync(file, "utf-8")).content;
16199
+ return matter20(fs8.readFileSync(file, "utf-8")).content;
16062
16200
  } catch {
16063
16201
  return "";
16064
16202
  }
@@ -16097,9 +16235,11 @@ export {
16097
16235
  LIFECYCLE_STATES2 as LIFECYCLE_STATES,
16098
16236
  LIFECYCLE_TRANSITIONS,
16099
16237
  OKF_DEFAULT_OUTPUT,
16238
+ OKF_EXPORT_PROCESS,
16100
16239
  OKF_RESERVED_FILES,
16101
16240
  OKF_TYPE_TABLE,
16102
16241
  OKF_VERSION,
16242
+ OkfExportError,
16103
16243
  POC_ARTIFACT_PATH,
16104
16244
  POC_REPORT_PREFIX,
16105
16245
  PRODUCTION_RUNBOOKS_DIR,
@@ -16203,6 +16343,7 @@ export {
16203
16343
  importWorkItem,
16204
16344
  integrationRegistry,
16205
16345
  isActiveState,
16346
+ isAgentInstruction,
16206
16347
  isDeferralActive,
16207
16348
  isInteractive,
16208
16349
  isModule,
package/dist/index.js CHANGED
@@ -20448,6 +20448,7 @@ import fs7 from "fs";
20448
20448
  import path11 from "path";
20449
20449
 
20450
20450
  // src/core/okf/mapping.ts
20451
+ import matter17 from "gray-matter";
20451
20452
  var OKF_TYPE_TABLE = {
20452
20453
  "business-knowledge": "Business Knowledge",
20453
20454
  "product-knowledge": "Product Knowledge",
@@ -20465,6 +20466,13 @@ var OKF_TYPE_TABLE = {
20465
20466
  };
20466
20467
  var WORK_ITEM_TYPES3 = /* @__PURE__ */ new Set(["feature", "bugfix", "hotfix", "spike", "chore"]);
20467
20468
  var REPORT_TYPES = /* @__PURE__ */ new Set(["impact-report", "drift-report", "savings-report", "poc-report"]);
20469
+ var AGENT_INSTRUCTION_TYPES = /* @__PURE__ */ new Set(["agent", "workflow", "prompt", "skill"]);
20470
+ function isAgentInstruction(a) {
20471
+ const t = (a.type || "").toLowerCase();
20472
+ if (AGENT_INSTRUCTION_TYPES.has(t)) return true;
20473
+ const p = a.relPath.toLowerCase();
20474
+ return p.includes("/agents/") || p.includes("/skills/") || p.includes("/workflows/");
20475
+ }
20468
20476
  function okfConceptType(a) {
20469
20477
  if (a.isWorkItem) return "Work Item";
20470
20478
  const t = (a.type || "").toLowerCase();
@@ -20487,6 +20495,7 @@ function conceptBundlePath(a, id) {
20487
20495
  const file = `${id}.md`;
20488
20496
  if (a.isWorkItem) return `delivery/work-items/${file}`;
20489
20497
  const t = (a.type || "").toLowerCase();
20498
+ if (isAgentInstruction(a)) return `agents/${file}`;
20490
20499
  if (t === "deprecation-plan") return `delivery/deprecations/${file}`;
20491
20500
  if (t === "production-runbook") return `delivery/runbooks/${file}`;
20492
20501
  if (t === "project-resource") return `resources/${file}`;
@@ -20538,6 +20547,14 @@ function conceptId(a) {
20538
20547
  const base = a.relPath.split("/").pop() ?? "";
20539
20548
  return slugify5(base.replace(/\.md$/, "")) || slugify5(a.relPath);
20540
20549
  }
20550
+ function readBody(a) {
20551
+ try {
20552
+ const body = matter17(readFile(a.filePath)).content.trim();
20553
+ return body || null;
20554
+ } catch {
20555
+ return null;
20556
+ }
20557
+ }
20541
20558
  function buildConcept(a) {
20542
20559
  const id = conceptId(a);
20543
20560
  if (!id) return null;
@@ -20551,12 +20568,13 @@ function buildConcept(a) {
20551
20568
  path: conceptBundlePath(a, id),
20552
20569
  sourcePath: a.relPath,
20553
20570
  related: a.isWorkItem ? workItemRelations(rawFm) : [],
20554
- body: null
20571
+ // Preserve the canonical Markdown body so the concept is consumable, not just discoverable (WI-066 P1).
20572
+ body: readBody(a)
20555
20573
  };
20556
20574
  }
20557
20575
 
20558
20576
  // src/core/impact-report.ts
20559
- import matter17 from "gray-matter";
20577
+ import matter18 from "gray-matter";
20560
20578
 
20561
20579
  // src/core/reporting-evidence.ts
20562
20580
  function graphHintFinding(hint) {
@@ -20693,7 +20711,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
20693
20711
  }
20694
20712
  }
20695
20713
  try {
20696
- const body = matter17(readFile(wi.filePath)).content;
20714
+ const body = matter18(readFile(wi.filePath)).content;
20697
20715
  if (hasSection(body, /acceptance|criterios de aceptaci/i)) withAcceptance++;
20698
20716
  else gaps.missing_acceptance_criteria.push(gapItem(wi, "Add an `## Acceptance Criteria` section."));
20699
20717
  if (hasSection(body, /definition of done|^#{1,6}\s*dod\b|definici[oó]n de (terminado|hecho)/i)) withDoD++;
@@ -21709,6 +21727,18 @@ function serializeSavingsJson(r) {
21709
21727
  return JSON.stringify(r, null, 2) + "\n";
21710
21728
  }
21711
21729
 
21730
+ // src/core/okf/types.ts
21731
+ var OKF_VERSION = "0.2";
21732
+ var OKF_EXPORT_PROCESS = "process:kaddo-okf-export";
21733
+ var OkfExportError = class extends Error {
21734
+ constructor(code, message) {
21735
+ super(message);
21736
+ this.code = code;
21737
+ this.name = "OkfExportError";
21738
+ }
21739
+ code;
21740
+ };
21741
+
21712
21742
  // src/core/okf/extras.ts
21713
21743
  function reportConcepts(dir, now = /* @__PURE__ */ new Date()) {
21714
21744
  const concepts = [];
@@ -21725,6 +21755,7 @@ function reportConcepts(dir, now = /* @__PURE__ */ new Date()) {
21725
21755
  tags: ["report"],
21726
21756
  path: `reports/${id}.md`,
21727
21757
  sourcePath: null,
21758
+ generatedBy: OKF_EXPORT_PROCESS,
21728
21759
  generatedAt: at,
21729
21760
  related: [],
21730
21761
  body
@@ -21779,9 +21810,6 @@ function externalCapsuleConcepts(dir) {
21779
21810
  });
21780
21811
  }
21781
21812
 
21782
- // src/core/okf/types.ts
21783
- var OKF_VERSION = "0.2";
21784
-
21785
21813
  // src/core/okf/export.ts
21786
21814
  var OKF_DEFAULT_OUTPUT = ".kaddo/okf";
21787
21815
  function frontmatter(data) {
@@ -21800,6 +21828,11 @@ function frontmatter(data) {
21800
21828
  lines.push(` - ${JSON.stringify(item)}`);
21801
21829
  }
21802
21830
  }
21831
+ } else if (v && typeof v === "object") {
21832
+ lines.push(`${k}:`);
21833
+ for (const [ik, iv] of Object.entries(v)) {
21834
+ if (iv != null) lines.push(` ${ik}: ${JSON.stringify(iv)}`);
21835
+ }
21803
21836
  } else {
21804
21837
  lines.push(`${k}: ${JSON.stringify(v)}`);
21805
21838
  }
@@ -21811,7 +21844,20 @@ function relLink(fromPath, toPath) {
21811
21844
  const rel = path11.posix.relative(path11.posix.dirname(fromPath), toPath);
21812
21845
  return rel.startsWith(".") ? rel : `./${rel}`;
21813
21846
  }
21814
- function renderConcept(c, byId) {
21847
+ function rewriteBodyLinks(body, sourcePath, srcToBundle, selfBundlePath) {
21848
+ const srcDir = path11.posix.dirname(sourcePath);
21849
+ return body.replace(/\]\(([^)]+)\)/g, (whole, href) => {
21850
+ const raw = href.trim();
21851
+ const bare = raw.split("#")[0].split(" ")[0];
21852
+ if (!bare || /^(https?:|mailto:|#)/.test(bare)) return whole;
21853
+ const candidate = bare.startsWith("/") ? bare.replace(/^\/+/, "") : path11.posix.normalize(path11.posix.join(srcDir, bare));
21854
+ const target = srcToBundle.get(candidate);
21855
+ if (!target) return whole;
21856
+ const anchor = raw.includes("#") ? "#" + raw.split("#").slice(1).join("#") : "";
21857
+ return `](${relLink(selfBundlePath, target)}${anchor})`;
21858
+ });
21859
+ }
21860
+ function renderConcept(c, byId, srcToBundle) {
21815
21861
  const data = {
21816
21862
  type: c.type,
21817
21863
  title: c.title,
@@ -21820,10 +21866,13 @@ function renderConcept(c, byId) {
21820
21866
  kaddo_id: c.id
21821
21867
  };
21822
21868
  if (c.sourcePath) data.sources = [{ resource: c.sourcePath }];
21823
- if (c.generatedAt) data.generated = { at: c.generatedAt };
21869
+ if (c.generatedBy || c.generatedAt) {
21870
+ data.generated = { ...c.generatedBy ? { by: c.generatedBy } : {}, ...c.generatedAt ? { at: c.generatedAt } : {} };
21871
+ }
21824
21872
  const parts = [frontmatter(data)];
21825
21873
  if (c.body) {
21826
- parts.push("", c.body.trim());
21874
+ const body = c.sourcePath ? rewriteBodyLinks(c.body, c.sourcePath, srcToBundle, c.path) : c.body;
21875
+ parts.push("", body.trim());
21827
21876
  } else {
21828
21877
  parts.push("", `# ${c.title}`);
21829
21878
  if (c.description) parts.push("", c.description);
@@ -21838,15 +21887,20 @@ function renderConcept(c, byId) {
21838
21887
  }
21839
21888
  return parts.join("\n") + "\n";
21840
21889
  }
21841
- function renderIndex(title, concepts, fromPath, root) {
21842
- const data = { type: "Index", title };
21843
- if (root) data.okf_version = OKF_VERSION;
21844
- const parts = [frontmatter(data), "", `# ${title}`, ""];
21890
+ function renderIndex(title, concepts, childDirs, fromPath, root) {
21891
+ const parts = [];
21892
+ if (root) parts.push(frontmatter({ okf_version: OKF_VERSION }), "");
21893
+ parts.push(`# ${title}`, "");
21845
21894
  if (root) parts.push(
21846
- `Open Knowledge Format bundle \u2014 version ${OKF_VERSION}. A portable projection of`,
21847
- "Kaddo knowledge. Kaddo remains the source of truth.",
21895
+ "Open Knowledge Format bundle \u2014 a portable projection of Kaddo knowledge.",
21896
+ "Kaddo remains the source of truth.",
21848
21897
  ""
21849
21898
  );
21899
+ if (childDirs.length > 0) {
21900
+ parts.push("## Sections");
21901
+ for (const d of [...childDirs].sort()) parts.push(`- [${d}/](${relLink(fromPath, `${d}/index.md`)})`);
21902
+ parts.push("");
21903
+ }
21850
21904
  const byType = /* @__PURE__ */ new Map();
21851
21905
  for (const c of concepts) {
21852
21906
  const l = byType.get(c.type) ?? [];
@@ -21856,84 +21910,168 @@ function renderIndex(title, concepts, fromPath, root) {
21856
21910
  for (const type of [...byType.keys()].sort()) {
21857
21911
  parts.push(`## ${type}`);
21858
21912
  for (const c of byType.get(type).sort((a, b) => a.id.localeCompare(b.id))) {
21859
- parts.push(`- [${c.title}](${relLink(fromPath, c.path)})`);
21913
+ const d = c.description ? ` \u2014 ${c.description}` : "";
21914
+ parts.push(`- [${c.title}](${relLink(fromPath, c.path)})${d}`);
21860
21915
  }
21861
21916
  parts.push("");
21862
21917
  }
21863
21918
  return parts.join("\n");
21864
21919
  }
21865
- function atomicWrite4(file, content) {
21866
- fs7.mkdirSync(path11.dirname(file), { recursive: true });
21867
- fs7.writeFileSync(file, content, "utf-8");
21868
- }
21869
21920
  var SENSITIVE_PATTERNS = [
21870
21921
  { re: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/, label: "private key block" },
21871
21922
  { re: /\bAKIA[0-9A-Z]{16}\b/, label: "AWS access key id" },
21872
21923
  { re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/, label: "GitHub token" },
21873
21924
  { re: /\b(?:password|secret|api[_-]?key|access[_-]?token)\b\s*[:=]\s*["']?[A-Za-z0-9+/_\-]{12,}/i, label: "inline credential" }
21874
21925
  ];
21875
- function scanSensitive(renderedPath, content) {
21876
- const hits = SENSITIVE_PATTERNS.filter((p) => p.re.test(content)).map((p) => p.label);
21877
- return hits.length > 0 ? [`${renderedPath}: possible ${[...new Set(hits)].join(", ")} \u2014 review before sharing.`] : [];
21926
+ function sensitiveLabels(content) {
21927
+ return [...new Set(SENSITIVE_PATTERNS.filter((p) => p.re.test(content)).map((p) => p.label))];
21928
+ }
21929
+ function assertSafeDestination(dir, outputDir) {
21930
+ const root = path11.resolve(dir);
21931
+ const out = path11.resolve(outputDir);
21932
+ const within = (child, parent) => {
21933
+ const rel = path11.relative(parent, child);
21934
+ return rel === "" || !rel.startsWith("..") && !path11.isAbsolute(rel);
21935
+ };
21936
+ if (out === root) throw new OkfExportError("UNSAFE_DESTINATION", "Refusing to export onto the project root.");
21937
+ if (within(root, out)) throw new OkfExportError("UNSAFE_DESTINATION", "Refusing to export onto a parent of the project.");
21938
+ for (const protectedDir of ["knowledge", "packages", "apps", "src", "node_modules", ".git"]) {
21939
+ const p = path11.join(root, protectedDir);
21940
+ if (out === p || within(out, p)) throw new OkfExportError("UNSAFE_DESTINATION", `Refusing to export into a protected directory: ${protectedDir}/`);
21941
+ }
21942
+ if (fs7.existsSync(out)) {
21943
+ try {
21944
+ const entries = fs7.readdirSync(out);
21945
+ const looksOkf = entries.includes("index.md") && /okf_version/.test(fs7.readFileSync(path11.join(out, "index.md"), "utf-8"));
21946
+ if (entries.length > 0 && !looksOkf) {
21947
+ throw new OkfExportError("UNSAFE_DESTINATION", `Destination is not empty and is not an OKF bundle: ${outputDir}. Use an empty or dedicated directory.`);
21948
+ }
21949
+ } catch (e) {
21950
+ if (e instanceof OkfExportError) throw e;
21951
+ }
21952
+ }
21953
+ }
21954
+ function detectCollisions(concepts) {
21955
+ const byId = /* @__PURE__ */ new Map();
21956
+ const byPath = /* @__PURE__ */ new Map();
21957
+ const errors = [];
21958
+ for (const c of concepts) {
21959
+ const prev = byId.get(c.id);
21960
+ if (prev && prev !== (c.sourcePath ?? "")) errors.push(`Concept id "${c.id}" is produced by two different sources: ${prev} and ${c.sourcePath}.`);
21961
+ else byId.set(c.id, c.sourcePath ?? "");
21962
+ const prevP = byPath.get(c.path);
21963
+ if (prevP && prevP !== c.id) errors.push(`Destination path "${c.path}" is claimed by two concepts: ${prevP} and ${c.id}.`);
21964
+ else byPath.set(c.path, c.id);
21965
+ }
21966
+ return errors;
21878
21967
  }
21879
21968
  function exportOkf(dir, opts = {}) {
21880
21969
  const outRel = opts.output ?? OKF_DEFAULT_OUTPUT;
21881
21970
  const outputDir = path11.isAbsolute(outRel) ? outRel : path11.join(dir, outRel);
21971
+ assertSafeDestination(dir, outputDir);
21882
21972
  const extraWarnings = [];
21883
21973
  const artifacts = discoverKnowledge(dir);
21884
- const concepts = [];
21885
- const seen = /* @__PURE__ */ new Set();
21974
+ const raw = [];
21886
21975
  const omittedCounts = /* @__PURE__ */ new Map();
21887
- const addConcept = (c) => {
21888
- if (!c || seen.has(c.id)) return;
21889
- seen.add(c.id);
21890
- concepts.push(c);
21891
- };
21976
+ const omittedConcepts = [];
21977
+ const bump = (type) => omittedCounts.set(type, (omittedCounts.get(type) ?? 0) + 1);
21978
+ const sameSource = /* @__PURE__ */ new Set();
21892
21979
  for (const a of artifacts) {
21980
+ if (isAgentInstruction(a) && !opts.withAgents) {
21981
+ bump(a.type || "agent");
21982
+ continue;
21983
+ }
21893
21984
  const c = buildConcept(a);
21894
21985
  if (!c) {
21895
- omittedCounts.set(a.type || "unknown", (omittedCounts.get(a.type || "unknown") ?? 0) + 1);
21986
+ bump(a.type || "unknown");
21896
21987
  continue;
21897
21988
  }
21898
- addConcept(c);
21989
+ const key = `${c.id}\0${c.sourcePath ?? ""}`;
21990
+ if (sameSource.has(key)) continue;
21991
+ sameSource.add(key);
21992
+ raw.push(c);
21899
21993
  }
21900
- for (const c of externalCapsuleConcepts(dir)) addConcept(c);
21994
+ for (const c of externalCapsuleConcepts(dir)) raw.push(c);
21901
21995
  if (opts.withReports) {
21902
- const { concepts: reports, warnings: warnings2 } = reportConcepts(dir, opts.now ?? /* @__PURE__ */ new Date());
21903
- for (const c of reports) addConcept(c);
21904
- extraWarnings.push(...warnings2);
21996
+ const { concepts: reports, warnings } = reportConcepts(dir, opts.now ?? /* @__PURE__ */ new Date());
21997
+ raw.push(...reports);
21998
+ extraWarnings.push(...warnings);
21999
+ }
22000
+ const collisions = detectCollisions(raw);
22001
+ if (collisions.length > 0) {
22002
+ throw new OkfExportError("IDENTITY_COLLISION", `Cannot export: ${collisions.length} unresolved identity collision(s):
22003
+ - ${collisions.join("\n- ")}`);
22004
+ }
22005
+ const concepts = [];
22006
+ for (const c of raw) {
22007
+ const hay = `${c.title}
22008
+ ${c.description ?? ""}
22009
+ ${c.body ?? ""}`;
22010
+ const labels = sensitiveLabels(hay);
22011
+ if (labels.length > 0) {
22012
+ omittedConcepts.push({ id: c.id, reason: `potential ${labels.join(", ")}` });
22013
+ continue;
22014
+ }
22015
+ concepts.push(c);
21905
22016
  }
21906
22017
  concepts.sort((a, b) => a.id.localeCompare(b.id));
21907
22018
  const byId = new Map(concepts.map((c) => [c.id, c]));
21908
- const layerOf = (p) => p.split("/")[0];
21909
- const byLayer = /* @__PURE__ */ new Map();
22019
+ const srcToBundle = /* @__PURE__ */ new Map();
22020
+ for (const c of concepts) if (c.sourcePath) srcToBundle.set(c.sourcePath, c.path);
22021
+ const files = /* @__PURE__ */ new Map();
22022
+ for (const c of concepts) files.set(c.path, renderConcept(c, byId, srcToBundle));
22023
+ const dirs = /* @__PURE__ */ new Map();
22024
+ const childDirs = /* @__PURE__ */ new Map();
21910
22025
  for (const c of concepts) {
21911
- const l = byLayer.get(layerOf(c.path)) ?? [];
21912
- l.push(c);
21913
- byLayer.set(layerOf(c.path), l);
21914
- }
21915
- fs7.rmSync(outputDir, { recursive: true, force: true });
21916
- fs7.mkdirSync(outputDir, { recursive: true });
21917
- const written = [];
21918
- const warnings = [];
21919
- const write = (bundlePath, content) => {
21920
- atomicWrite4(path11.join(outputDir, bundlePath), content);
21921
- written.push(bundlePath);
21922
- warnings.push(...scanSensitive(bundlePath, content));
21923
- };
21924
- for (const c of concepts) write(c.path, renderConcept(c, byId));
21925
- for (const layer2 of [...byLayer.keys()].sort()) {
21926
- const title = layer2.charAt(0).toUpperCase() + layer2.slice(1);
21927
- write(`${layer2}/index.md`, renderIndex(`${title} Knowledge`, byLayer.get(layer2), `${layer2}/index.md`, false));
22026
+ const d = path11.posix.dirname(c.path);
22027
+ (dirs.get(d) ?? dirs.set(d, []).get(d)).push(c);
22028
+ const segs = d === "." ? [] : d.split("/");
22029
+ for (let i = 0; i < segs.length; i++) {
22030
+ const parent = segs.slice(0, i).join("/") || ".";
22031
+ const child = segs.slice(0, i + 1).join("/");
22032
+ (childDirs.get(parent) ?? childDirs.set(parent, /* @__PURE__ */ new Set()).get(parent)).add(child);
22033
+ }
22034
+ }
22035
+ let indexCount = 0;
22036
+ for (const [d, cs] of dirs) {
22037
+ if (d === ".") continue;
22038
+ const title = d.split("/").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join(" / ");
22039
+ const kids = [...childDirs.get(d) ?? []].map((c) => c.split("/").pop());
22040
+ files.set(`${d}/index.md`, renderIndex(title, cs, kids, `${d}/index.md`, false));
22041
+ indexCount++;
22042
+ }
22043
+ const rootConcepts = dirs.get(".") ?? [];
22044
+ const rootKids = [...childDirs.get(".") ?? []];
22045
+ files.set("index.md", renderIndex("Knowledge bundle", rootConcepts, rootKids, "index.md", true));
22046
+ indexCount++;
22047
+ const staging = `${outputDir}.staging-${process.pid}-${Date.now()}`;
22048
+ try {
22049
+ fs7.rmSync(staging, { recursive: true, force: true });
22050
+ for (const [rel, content] of files) {
22051
+ const full = path11.join(staging, rel);
22052
+ fs7.mkdirSync(path11.dirname(full), { recursive: true });
22053
+ fs7.writeFileSync(full, content, "utf-8");
22054
+ }
22055
+ const backup = `${outputDir}.old-${process.pid}-${Date.now()}`;
22056
+ if (fs7.existsSync(outputDir)) fs7.renameSync(outputDir, backup);
22057
+ try {
22058
+ fs7.renameSync(staging, outputDir);
22059
+ } catch (e) {
22060
+ if (fs7.existsSync(backup)) fs7.renameSync(backup, outputDir);
22061
+ throw e;
22062
+ }
22063
+ fs7.rmSync(backup, { recursive: true, force: true });
22064
+ } finally {
22065
+ fs7.rmSync(staging, { recursive: true, force: true });
21928
22066
  }
21929
- write("index.md", renderIndex("Knowledge bundle", concepts, "index.md", true));
21930
- written.sort();
22067
+ const written = [...files.keys()].sort();
21931
22068
  return {
21932
22069
  outputDir,
21933
22070
  conceptCount: concepts.length,
21934
- indexCount: byLayer.size + 1,
22071
+ indexCount,
21935
22072
  omitted: [...omittedCounts.entries()].map(([type, count]) => ({ type, count })).sort((a, b) => a.type.localeCompare(b.type)),
21936
- warnings: [...warnings, ...extraWarnings].sort(),
22073
+ omittedConcepts: omittedConcepts.sort((a, b) => a.id.localeCompare(b.id)),
22074
+ warnings: extraWarnings.sort(),
21937
22075
  files: written
21938
22076
  };
21939
22077
  }
@@ -21941,7 +22079,7 @@ function exportOkf(dir, opts = {}) {
21941
22079
  // src/core/okf/validate.ts
21942
22080
  import fs8 from "fs";
21943
22081
  import path12 from "path";
21944
- import matter18 from "gray-matter";
22082
+ import matter19 from "gray-matter";
21945
22083
  function walk(root) {
21946
22084
  const out = [];
21947
22085
  const rec = (d) => {
@@ -21988,16 +22126,16 @@ function validateOkf(dir, opts = {}) {
21988
22126
  const isIndex = path12.basename(file) === "index.md";
21989
22127
  let data = {};
21990
22128
  try {
21991
- data = matter18(fs8.readFileSync(file, "utf-8")).data ?? {};
22129
+ data = matter19(fs8.readFileSync(file, "utf-8")).data ?? {};
21992
22130
  } catch {
21993
22131
  findings.push({ level: "conformance", file: r, message: "Invalid YAML frontmatter." });
21994
22132
  continue;
21995
22133
  }
21996
22134
  const type = typeof data.type === "string" ? data.type.trim() : "";
21997
- if (!type) {
21998
- findings.push(isIndex ? { level: "warning", file: r, message: "Index has no type." } : { level: "conformance", file: r, message: "Concept has no non-empty `type`." });
22135
+ if (!isIndex) {
22136
+ if (!type) findings.push({ level: "conformance", file: r, message: "Concept has no non-empty `type`." });
22137
+ conceptCount++;
21999
22138
  }
22000
- if (!isIndex) conceptCount++;
22001
22139
  if (r === "index.md") {
22002
22140
  const v = typeof data.okf_version === "string" ? data.okf_version : data.okf_version != null ? String(data.okf_version) : "";
22003
22141
  if (!v) findings.push({ level: "warning", file: r, message: "Root index does not declare okf_version." });
@@ -22010,7 +22148,7 @@ function validateOkf(dir, opts = {}) {
22010
22148
  }
22011
22149
  const body = (() => {
22012
22150
  try {
22013
- return matter18(fs8.readFileSync(file, "utf-8")).content;
22151
+ return matter19(fs8.readFileSync(file, "utf-8")).content;
22014
22152
  } catch {
22015
22153
  return "";
22016
22154
  }
@@ -22030,15 +22168,26 @@ function validateOkf(dir, opts = {}) {
22030
22168
 
22031
22169
  // src/commands/okf.ts
22032
22170
  function runOkfExport(opts = {}, dir = cwd()) {
22033
- const res = exportOkf(dir, { output: opts.output, withReports: opts.withReports });
22171
+ let res;
22172
+ try {
22173
+ res = exportOkf(dir, { output: opts.output, withReports: opts.withReports, withAgents: opts.withAgents });
22174
+ } catch (e) {
22175
+ if (e instanceof OkfExportError) {
22176
+ console.error(`okf export refused (${e.code}): ${e.message}`);
22177
+ process.exit(1);
22178
+ }
22179
+ throw e;
22180
+ }
22034
22181
  if (opts.json) {
22035
22182
  console.log(JSON.stringify(res, null, 2));
22036
22183
  return;
22037
22184
  }
22038
22185
  intro("kaddo okf export");
22039
22186
  log.success(`Exported ${res.conceptCount} concept(s) + ${res.indexCount} index(es) to ${res.outputDir}`);
22040
- if (res.omitted.length > 0) {
22041
- log.info(`Omitted: ${res.omitted.map((o) => `${o.count}\xD7 ${o.type}`).join(", ")}`);
22187
+ if (res.omitted.length > 0) log.info(`Omitted by type: ${res.omitted.map((o) => `${o.count}\xD7 ${o.type}`).join(", ")}`);
22188
+ if (res.omittedConcepts.length > 0) {
22189
+ log.warn(`Omitted ${res.omittedConcepts.length} concept(s) with potentially sensitive content:`);
22190
+ for (const o of res.omittedConcepts) console.log(` \xB7 ${o.id} \u2014 ${o.reason}`);
22042
22191
  }
22043
22192
  for (const w of res.warnings) log.warn(w);
22044
22193
  outro("Review the bundle before sharing it externally (it may contain project knowledge).");
@@ -22070,14 +22219,14 @@ function runOkfValidate(location, opts = {}, dir = cwd()) {
22070
22219
  }
22071
22220
 
22072
22221
  // src/services/integrations.ts
22073
- import matter20 from "gray-matter";
22222
+ import matter21 from "gray-matter";
22074
22223
  import { parse as parseYaml19, stringify as stringifyYaml10 } from "yaml";
22075
22224
 
22076
22225
  // src/core/work-item-write.ts
22077
22226
  import fs9 from "fs";
22078
22227
  import path13 from "path";
22079
22228
  import crypto2 from "crypto";
22080
- import matter19 from "gray-matter";
22229
+ import matter20 from "gray-matter";
22081
22230
  var WORK_ITEMS_DIR3 = "knowledge/delivery/work-items";
22082
22231
  var WorkItemWriteError = class extends Error {
22083
22232
  constructor(code, message) {
@@ -22111,7 +22260,7 @@ function nextWorkItemId2(dir) {
22111
22260
  walk2(wiDir);
22112
22261
  return `WI-${String(max + 1).padStart(3, "0")}`;
22113
22262
  }
22114
- function atomicWrite5(filePath, content) {
22263
+ function atomicWrite4(filePath, content) {
22115
22264
  fs9.mkdirSync(path13.dirname(filePath), { recursive: true });
22116
22265
  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
22117
22266
  fs9.writeFileSync(tmp, content, "utf-8");
@@ -22181,7 +22330,7 @@ function ensureH1(body, title) {
22181
22330
  ${trimmed}`;
22182
22331
  }
22183
22332
  function serialize3(data, body) {
22184
- return matter19.stringify(`
22333
+ return matter20.stringify(`
22185
22334
  ${body.trim()}
22186
22335
  `, data);
22187
22336
  }
@@ -22250,7 +22399,7 @@ function createWorkItem(dir, opts) {
22250
22399
  const filePath = join(dir, relPath);
22251
22400
  if (exists(filePath)) throw new WorkItemWriteError("INVALID_INPUT", `Work Item file already exists: ${relPath}`);
22252
22401
  const raw = serialize3(data, body);
22253
- atomicWrite5(filePath, raw);
22402
+ atomicWrite4(filePath, raw);
22254
22403
  return { id, path: relPath, revision: revisionOf(raw) };
22255
22404
  }
22256
22405
 
@@ -23258,7 +23407,7 @@ function findLinkedWorkItem(dir, integrationId, externalId) {
23258
23407
  for (const art of discoverWorkItems(dir)) {
23259
23408
  let data;
23260
23409
  try {
23261
- data = matter20(readFile(art.filePath)).data;
23410
+ data = matter21(readFile(art.filePath)).data;
23262
23411
  } catch {
23263
23412
  continue;
23264
23413
  }
@@ -23914,7 +24063,7 @@ function runAssetsUpdate(kind, opts = {}) {
23914
24063
  // src/commands/ready.ts
23915
24064
  import fs11 from "fs";
23916
24065
  import path14 from "path";
23917
- import matter21 from "gray-matter";
24066
+ import matter22 from "gray-matter";
23918
24067
  function validateReadiness(content, frontmatter2) {
23919
24068
  const warnings = [];
23920
24069
  const body = content.replace(/^---[\s\S]*?---/, "").trim();
@@ -23968,11 +24117,11 @@ function isResolvedSection(text2) {
23968
24117
  }
23969
24118
  function transitionToReady(filePath) {
23970
24119
  const raw = readFile(filePath);
23971
- const { data, content } = matter21(raw);
24120
+ const { data, content } = matter22(raw);
23972
24121
  const today3 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
23973
24122
  data.status = "ready";
23974
24123
  data.ready_at = today3;
23975
- const newContent = matter21.stringify(content, data);
24124
+ const newContent = matter22.stringify(content, data);
23976
24125
  const posix2 = filePath.replace(/\\/g, "/");
23977
24126
  let newPath = filePath;
23978
24127
  if (posix2.includes("/work-items/draft/")) {
@@ -24012,7 +24161,7 @@ async function runReady(id, opts = {}) {
24012
24161
  process.exit(1);
24013
24162
  }
24014
24163
  const raw = readFile(wi.filePath);
24015
- const { data } = matter21(raw);
24164
+ const { data } = matter22(raw);
24016
24165
  const source2 = parseWorkItemSource(data);
24017
24166
  const warnings = validateReadiness(raw, data);
24018
24167
  log.info(`Work Item found:`);
@@ -24188,10 +24337,10 @@ async function runAdmin(opts = {}) {
24188
24337
  // src/core/work-item-import.ts
24189
24338
  import crypto3 from "crypto";
24190
24339
  import fs12 from "fs";
24191
- import matter23 from "gray-matter";
24340
+ import matter24 from "gray-matter";
24192
24341
 
24193
24342
  // src/core/work-items.ts
24194
- import matter22 from "gray-matter";
24343
+ import matter23 from "gray-matter";
24195
24344
  function computeRefinementStatus(wi) {
24196
24345
  const aspects = {
24197
24346
  outcome: Boolean(wi.currentBehavior?.trim() || wi.targetBehavior?.trim()),
@@ -24230,7 +24379,7 @@ function getWorkItem(dir, workItemId) {
24230
24379
  const match = artifacts.find((a) => (a.id || a.title) === workItemId);
24231
24380
  if (!match) throw new WorkItemNotFoundError(workItemId);
24232
24381
  const base = toListItem(match);
24233
- const body = readBody(match.filePath);
24382
+ const body = readBody2(match.filePath);
24234
24383
  const sections = splitSections(body);
24235
24384
  const fm2 = match.rawFrontmatter;
24236
24385
  const knowledge = discoverKnowledge(dir).filter((a) => !a.isWorkItem);
@@ -24324,10 +24473,10 @@ function parseOriginalSnapshot(fm2) {
24324
24473
  updated_at: typeof o.updated_at === "string" ? o.updated_at : void 0
24325
24474
  };
24326
24475
  }
24327
- function readBody(filePath) {
24476
+ function readBody2(filePath) {
24328
24477
  try {
24329
24478
  const raw = readFile(filePath);
24330
- return matter22(raw).content;
24479
+ return matter23(raw).content;
24331
24480
  } catch {
24332
24481
  return "";
24333
24482
  }
@@ -24786,7 +24935,7 @@ function detectFormat(raw) {
24786
24935
  if (!trimmed) throw new ImportError("EMPTY_INPUT", "Import content is empty.");
24787
24936
  if (trimmed.startsWith("---")) {
24788
24937
  try {
24789
- const { data } = matter23(trimmed);
24938
+ const { data } = matter24(trimmed);
24790
24939
  if (data && typeof data === "object" && Object.keys(data).length > 0) {
24791
24940
  const d = data;
24792
24941
  if (d.type === "work-item" || d.id && typeof d.id === "string" && /^WI-\d+/.test(d.id)) {
@@ -24808,7 +24957,7 @@ function parseContent(raw) {
24808
24957
  let bodyText = trimmed;
24809
24958
  if (format === "kaddo-frontmatter" || format === "markdown-frontmatter") {
24810
24959
  try {
24811
- const parsed = matter23(trimmed);
24960
+ const parsed = matter24(trimmed);
24812
24961
  frontmatterFields = parsed.data ?? {};
24813
24962
  bodyText = parsed.content.trim();
24814
24963
  } catch {
@@ -24905,7 +25054,7 @@ function findDuplicateByHash(dir, hash) {
24905
25054
  const raw = readFile(item.filePath);
24906
25055
  if (!raw) continue;
24907
25056
  try {
24908
- const { data } = matter23(raw);
25057
+ const { data } = matter24(raw);
24909
25058
  const source2 = data?.source;
24910
25059
  if (source2 && typeof source2 === "object" && !Array.isArray(source2)) {
24911
25060
  const s = source2;
@@ -25146,7 +25295,7 @@ ${report.handoff}
25146
25295
  }
25147
25296
 
25148
25297
  // src/commands/verify.ts
25149
- import matter24 from "gray-matter";
25298
+ import matter25 from "gray-matter";
25150
25299
 
25151
25300
  // src/core/implementation-evidence.ts
25152
25301
  var WorkItemNotInProgressError = class extends Error {
@@ -25423,7 +25572,7 @@ async function runVerify(workItemId, opts = {}) {
25423
25572
  }
25424
25573
  const changedPaths = await getModifiedFiles("head");
25425
25574
  const raw = readFile(match.filePath);
25426
- const parsed = matter24(raw);
25575
+ const parsed = matter25(raw);
25427
25576
  const fm2 = parsed.data;
25428
25577
  const acs = extractACsFromBody(parsed.content);
25429
25578
  const existingEvidence = fm2.implementation_evidence;
@@ -25541,13 +25690,13 @@ async function runVerify(workItemId, opts = {}) {
25541
25690
  if (shouldPersist) {
25542
25691
  const filePath = match.filePath;
25543
25692
  const wiRaw = readFile(filePath);
25544
- const wiParsed = matter24(wiRaw);
25693
+ const wiParsed = matter25(wiRaw);
25545
25694
  const data = wiParsed.data;
25546
25695
  data.implementation_evidence = verification.implementationEvidence;
25547
25696
  data.implementation_status = verification.implementationStatus;
25548
25697
  data.validation_status = verification.validationStatus;
25549
25698
  data.verified_at = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
25550
- const newRaw = matter24.stringify(wiParsed.content, data);
25699
+ const newRaw = matter25.stringify(wiParsed.content, data);
25551
25700
  writeFile(filePath, newRaw);
25552
25701
  log.success("Work Item frontmatter updated with verification evidence.");
25553
25702
  }
@@ -25825,7 +25974,7 @@ function runTelemetryDisable() {
25825
25974
  }
25826
25975
 
25827
25976
  // src/core/initiative-write.ts
25828
- import matter25 from "gray-matter";
25977
+ import matter26 from "gray-matter";
25829
25978
  var WORK_ITEMS_DIR4 = "knowledge/delivery/work-items";
25830
25979
  var DRAFT_DIR2 = `${WORK_ITEMS_DIR4}/draft`;
25831
25980
  var InitiativeWriteError = class extends Error {
@@ -25937,7 +26086,7 @@ function buildInitiativeContent(id, input) {
25937
26086
  if (input.priority) data.priority = input.priority;
25938
26087
  if (input.source) data.source = input.source;
25939
26088
  if (input.sourceId) data.source_id = input.sourceId;
25940
- return matter25.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
26089
+ return matter26.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
25941
26090
  }
25942
26091
  function createInitiative(dir, input) {
25943
26092
  if (!input.title?.trim()) throw new InitiativeWriteError("Initiative title is required.");
@@ -25961,10 +26110,10 @@ function transitionInitiative(dir, id, to) {
25961
26110
  throw new InitiativeWriteError(`Invalid transition ${ini.status} \u2192 ${to}.`);
25962
26111
  }
25963
26112
  const raw = readFile(ini.filePath);
25964
- const { data, content } = matter25(raw, {});
26113
+ const { data, content } = matter26(raw, {});
25965
26114
  data.status = to;
25966
26115
  if (to === "completed") data.completed_at = today2();
25967
- const newContent = matter25.stringify(content, data);
26116
+ const newContent = matter26.stringify(content, data);
25968
26117
  writeFile(ini.filePath, newContent);
25969
26118
  const updated = parseInitiative(dir, ini.filePath, newContent);
25970
26119
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after transition.");
@@ -26033,7 +26182,7 @@ function buildWorkItemContent(wiId, iniId, candidate) {
26033
26182
  "_What did we learn? Update after completion._",
26034
26183
  ""
26035
26184
  ].join("\n");
26036
- return matter25.stringify("\n" + body, data);
26185
+ return matter26.stringify("\n" + body, data);
26037
26186
  }
26038
26187
  function materializeCandidate(dir, id, candidateId) {
26039
26188
  const ini = getInitiative(dir, id);
@@ -26050,13 +26199,13 @@ function materializeCandidate(dir, id, candidateId) {
26050
26199
  ensureDir(join(dir, DRAFT_DIR2));
26051
26200
  writeFile(join(dir, DRAFT_DIR2, fileName), buildWorkItemContent(wiId, ini.id, candidate));
26052
26201
  const raw = readFile(ini.filePath);
26053
- const { data, content } = matter25(raw, {});
26202
+ const { data, content } = matter26(raw, {});
26054
26203
  const cands = Array.isArray(data.candidates) ? data.candidates : [];
26055
26204
  for (const c of cands) {
26056
26205
  if (c && typeof c === "object" && String(c.id) === candidateId) c.materialized_as = wiId;
26057
26206
  }
26058
26207
  data.candidates = cands;
26059
- const newContent = matter25.stringify(content, data);
26208
+ const newContent = matter26.stringify(content, data);
26060
26209
  writeFile(ini.filePath, newContent);
26061
26210
  const updated = parseInitiative(dir, ini.filePath, newContent);
26062
26211
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
@@ -26462,7 +26611,7 @@ deprecationRunbookCmd.command("context <planId> <targetId>").description("Show b
26462
26611
  deprecationRunbookCmd.command("create <planId> <targetId>").description("Create a production runbook proposal; execution always remains manual").option("--json", "Output JSON").action((planId, targetId, opts) => runDeprecationRunbookCreate(planId, targetId, cwd(), opts));
26463
26612
  deprecationRunbookCmd.command("validate <id>").description("Validate required sections and the human approval boundary").option("--json", "Output JSON").action((id, opts) => runDeprecationRunbookValidate(id, cwd(), opts));
26464
26613
  var okfCmd = program.command("okf").description("Open Knowledge Format (OKF v0.2) \u2014 export/validate a portable knowledge bundle (optional interoperability)");
26465
- okfCmd.command("export").description("Export canonical knowledge as an OKF v0.2 bundle (read-only; default .kaddo/okf)").option("--output <dir>", "Output directory (default: .kaddo/okf)").option("--with-reports", "Also project Impact/Drift/Savings reports as concepts (adds a generation timestamp)").option("--json", "Output JSON").action((opts) => runOkfExport(opts, cwd()));
26614
+ okfCmd.command("export").description("Export canonical knowledge as an OKF v0.2 bundle (read-only; default .kaddo/okf)").option("--output <dir>", "Output directory (default: .kaddo/okf)").option("--with-reports", "Also project Impact/Drift/Savings reports as concepts (adds a generation timestamp)").option("--with-agents", "Also include agent/workflow instruction docs (under agents/); excluded by default").option("--json", "Output JSON").action((opts) => runOkfExport(opts, cwd()));
26466
26615
  okfCmd.command("validate [location]").description("Validate an OKF bundle: conformance errors vs warnings vs info (read-only, permissive)").option("--json", "Output JSON").action((location, opts) => runOkfValidate(location, opts, cwd()));
26467
26616
  var integrationsCmd = program.command("integrations").description("Connect Kaddo to external work systems (read-first; import requires human confirmation)");
26468
26617
  integrationsCmd.command("list").description("List configured integrations and their capabilities").option("--json", "Output JSON").action((opts) => runIntegrationsList(cwd(), opts));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kaddo/cli",
3
- "version": "3.125.0",
3
+ "version": "3.126.0",
4
4
  "description": "Knowledge Driven Development toolkit",
5
5
  "license": "MIT",
6
6
  "repository": {