@kaddo/cli 3.125.0 → 3.126.1

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 +206 -64
  2. package/dist/index.js +248 -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.split("/").pop()}/](${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,169 @@ 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
+ const allDirs = /* @__PURE__ */ new Set([...dirs.keys(), ...childDirs.keys()]);
16085
+ for (const d of allDirs) {
16086
+ if (d === ".") continue;
16087
+ const title = d.split("/").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join(" / ");
16088
+ const kids = [...childDirs.get(d) ?? []];
16089
+ files.set(`${d}/index.md`, renderIndex(title, dirs.get(d) ?? [], kids, `${d}/index.md`, false));
16090
+ indexCount++;
16091
+ }
16092
+ const rootConcepts = dirs.get(".") ?? [];
16093
+ const rootKids = [...childDirs.get(".") ?? []];
16094
+ files.set("index.md", renderIndex("Knowledge bundle", rootConcepts, rootKids, "index.md", true));
16095
+ indexCount++;
16096
+ const staging = `${outputDir}.staging-${process.pid}-${Date.now()}`;
16097
+ try {
16098
+ fs7.rmSync(staging, { recursive: true, force: true });
16099
+ for (const [rel, content] of files) {
16100
+ const full = path6.join(staging, rel);
16101
+ fs7.mkdirSync(path6.dirname(full), { recursive: true });
16102
+ fs7.writeFileSync(full, content, "utf-8");
16103
+ }
16104
+ const backup = `${outputDir}.old-${process.pid}-${Date.now()}`;
16105
+ if (fs7.existsSync(outputDir)) fs7.renameSync(outputDir, backup);
16106
+ try {
16107
+ fs7.renameSync(staging, outputDir);
16108
+ } catch (e) {
16109
+ if (fs7.existsSync(backup)) fs7.renameSync(backup, outputDir);
16110
+ throw e;
16111
+ }
16112
+ fs7.rmSync(backup, { recursive: true, force: true });
16113
+ } finally {
16114
+ fs7.rmSync(staging, { recursive: true, force: true });
16115
+ }
16116
+ const written = [...files.keys()].sort();
15979
16117
  return {
15980
16118
  outputDir,
15981
16119
  conceptCount: concepts.length,
15982
- indexCount: byLayer.size + 1,
16120
+ indexCount,
15983
16121
  omitted: [...omittedCounts.entries()].map(([type, count]) => ({ type, count })).sort((a, b) => a.type.localeCompare(b.type)),
15984
- warnings: [...warnings, ...extraWarnings].sort(),
16122
+ omittedConcepts: omittedConcepts.sort((a, b) => a.id.localeCompare(b.id)),
16123
+ warnings: extraWarnings.sort(),
15985
16124
  files: written
15986
16125
  };
15987
16126
  }
@@ -15989,7 +16128,7 @@ function exportOkf(dir, opts = {}) {
15989
16128
  // src/core/okf/validate.ts
15990
16129
  import fs8 from "fs";
15991
16130
  import path7 from "path";
15992
- import matter19 from "gray-matter";
16131
+ import matter20 from "gray-matter";
15993
16132
  function walk(root) {
15994
16133
  const out = [];
15995
16134
  const rec = (d) => {
@@ -16036,16 +16175,16 @@ function validateOkf(dir, opts = {}) {
16036
16175
  const isIndex = path7.basename(file) === "index.md";
16037
16176
  let data = {};
16038
16177
  try {
16039
- data = matter19(fs8.readFileSync(file, "utf-8")).data ?? {};
16178
+ data = matter20(fs8.readFileSync(file, "utf-8")).data ?? {};
16040
16179
  } catch {
16041
16180
  findings.push({ level: "conformance", file: r, message: "Invalid YAML frontmatter." });
16042
16181
  continue;
16043
16182
  }
16044
16183
  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`." });
16184
+ if (!isIndex) {
16185
+ if (!type) findings.push({ level: "conformance", file: r, message: "Concept has no non-empty `type`." });
16186
+ conceptCount++;
16047
16187
  }
16048
- if (!isIndex) conceptCount++;
16049
16188
  if (r === "index.md") {
16050
16189
  const v = typeof data.okf_version === "string" ? data.okf_version : data.okf_version != null ? String(data.okf_version) : "";
16051
16190
  if (!v) findings.push({ level: "warning", file: r, message: "Root index does not declare okf_version." });
@@ -16058,7 +16197,7 @@ function validateOkf(dir, opts = {}) {
16058
16197
  }
16059
16198
  const body = (() => {
16060
16199
  try {
16061
- return matter19(fs8.readFileSync(file, "utf-8")).content;
16200
+ return matter20(fs8.readFileSync(file, "utf-8")).content;
16062
16201
  } catch {
16063
16202
  return "";
16064
16203
  }
@@ -16097,9 +16236,11 @@ export {
16097
16236
  LIFECYCLE_STATES2 as LIFECYCLE_STATES,
16098
16237
  LIFECYCLE_TRANSITIONS,
16099
16238
  OKF_DEFAULT_OUTPUT,
16239
+ OKF_EXPORT_PROCESS,
16100
16240
  OKF_RESERVED_FILES,
16101
16241
  OKF_TYPE_TABLE,
16102
16242
  OKF_VERSION,
16243
+ OkfExportError,
16103
16244
  POC_ARTIFACT_PATH,
16104
16245
  POC_REPORT_PREFIX,
16105
16246
  PRODUCTION_RUNBOOKS_DIR,
@@ -16203,6 +16344,7 @@ export {
16203
16344
  importWorkItem,
16204
16345
  integrationRegistry,
16205
16346
  isActiveState,
16347
+ isAgentInstruction,
16206
16348
  isDeferralActive,
16207
16349
  isInteractive,
16208
16350
  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.split("/").pop()}/](${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,169 @@ 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
+ const allDirs = /* @__PURE__ */ new Set([...dirs.keys(), ...childDirs.keys()]);
22037
+ for (const d of allDirs) {
22038
+ if (d === ".") continue;
22039
+ const title = d.split("/").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join(" / ");
22040
+ const kids = [...childDirs.get(d) ?? []];
22041
+ files.set(`${d}/index.md`, renderIndex(title, dirs.get(d) ?? [], kids, `${d}/index.md`, false));
22042
+ indexCount++;
22043
+ }
22044
+ const rootConcepts = dirs.get(".") ?? [];
22045
+ const rootKids = [...childDirs.get(".") ?? []];
22046
+ files.set("index.md", renderIndex("Knowledge bundle", rootConcepts, rootKids, "index.md", true));
22047
+ indexCount++;
22048
+ const staging = `${outputDir}.staging-${process.pid}-${Date.now()}`;
22049
+ try {
22050
+ fs7.rmSync(staging, { recursive: true, force: true });
22051
+ for (const [rel, content] of files) {
22052
+ const full = path11.join(staging, rel);
22053
+ fs7.mkdirSync(path11.dirname(full), { recursive: true });
22054
+ fs7.writeFileSync(full, content, "utf-8");
22055
+ }
22056
+ const backup = `${outputDir}.old-${process.pid}-${Date.now()}`;
22057
+ if (fs7.existsSync(outputDir)) fs7.renameSync(outputDir, backup);
22058
+ try {
22059
+ fs7.renameSync(staging, outputDir);
22060
+ } catch (e) {
22061
+ if (fs7.existsSync(backup)) fs7.renameSync(backup, outputDir);
22062
+ throw e;
22063
+ }
22064
+ fs7.rmSync(backup, { recursive: true, force: true });
22065
+ } finally {
22066
+ fs7.rmSync(staging, { recursive: true, force: true });
21928
22067
  }
21929
- write("index.md", renderIndex("Knowledge bundle", concepts, "index.md", true));
21930
- written.sort();
22068
+ const written = [...files.keys()].sort();
21931
22069
  return {
21932
22070
  outputDir,
21933
22071
  conceptCount: concepts.length,
21934
- indexCount: byLayer.size + 1,
22072
+ indexCount,
21935
22073
  omitted: [...omittedCounts.entries()].map(([type, count]) => ({ type, count })).sort((a, b) => a.type.localeCompare(b.type)),
21936
- warnings: [...warnings, ...extraWarnings].sort(),
22074
+ omittedConcepts: omittedConcepts.sort((a, b) => a.id.localeCompare(b.id)),
22075
+ warnings: extraWarnings.sort(),
21937
22076
  files: written
21938
22077
  };
21939
22078
  }
@@ -21941,7 +22080,7 @@ function exportOkf(dir, opts = {}) {
21941
22080
  // src/core/okf/validate.ts
21942
22081
  import fs8 from "fs";
21943
22082
  import path12 from "path";
21944
- import matter18 from "gray-matter";
22083
+ import matter19 from "gray-matter";
21945
22084
  function walk(root) {
21946
22085
  const out = [];
21947
22086
  const rec = (d) => {
@@ -21988,16 +22127,16 @@ function validateOkf(dir, opts = {}) {
21988
22127
  const isIndex = path12.basename(file) === "index.md";
21989
22128
  let data = {};
21990
22129
  try {
21991
- data = matter18(fs8.readFileSync(file, "utf-8")).data ?? {};
22130
+ data = matter19(fs8.readFileSync(file, "utf-8")).data ?? {};
21992
22131
  } catch {
21993
22132
  findings.push({ level: "conformance", file: r, message: "Invalid YAML frontmatter." });
21994
22133
  continue;
21995
22134
  }
21996
22135
  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`." });
22136
+ if (!isIndex) {
22137
+ if (!type) findings.push({ level: "conformance", file: r, message: "Concept has no non-empty `type`." });
22138
+ conceptCount++;
21999
22139
  }
22000
- if (!isIndex) conceptCount++;
22001
22140
  if (r === "index.md") {
22002
22141
  const v = typeof data.okf_version === "string" ? data.okf_version : data.okf_version != null ? String(data.okf_version) : "";
22003
22142
  if (!v) findings.push({ level: "warning", file: r, message: "Root index does not declare okf_version." });
@@ -22010,7 +22149,7 @@ function validateOkf(dir, opts = {}) {
22010
22149
  }
22011
22150
  const body = (() => {
22012
22151
  try {
22013
- return matter18(fs8.readFileSync(file, "utf-8")).content;
22152
+ return matter19(fs8.readFileSync(file, "utf-8")).content;
22014
22153
  } catch {
22015
22154
  return "";
22016
22155
  }
@@ -22030,15 +22169,26 @@ function validateOkf(dir, opts = {}) {
22030
22169
 
22031
22170
  // src/commands/okf.ts
22032
22171
  function runOkfExport(opts = {}, dir = cwd()) {
22033
- const res = exportOkf(dir, { output: opts.output, withReports: opts.withReports });
22172
+ let res;
22173
+ try {
22174
+ res = exportOkf(dir, { output: opts.output, withReports: opts.withReports, withAgents: opts.withAgents });
22175
+ } catch (e) {
22176
+ if (e instanceof OkfExportError) {
22177
+ console.error(`okf export refused (${e.code}): ${e.message}`);
22178
+ process.exit(1);
22179
+ }
22180
+ throw e;
22181
+ }
22034
22182
  if (opts.json) {
22035
22183
  console.log(JSON.stringify(res, null, 2));
22036
22184
  return;
22037
22185
  }
22038
22186
  intro("kaddo okf export");
22039
22187
  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(", ")}`);
22188
+ if (res.omitted.length > 0) log.info(`Omitted by type: ${res.omitted.map((o) => `${o.count}\xD7 ${o.type}`).join(", ")}`);
22189
+ if (res.omittedConcepts.length > 0) {
22190
+ log.warn(`Omitted ${res.omittedConcepts.length} concept(s) with potentially sensitive content:`);
22191
+ for (const o of res.omittedConcepts) console.log(` \xB7 ${o.id} \u2014 ${o.reason}`);
22042
22192
  }
22043
22193
  for (const w of res.warnings) log.warn(w);
22044
22194
  outro("Review the bundle before sharing it externally (it may contain project knowledge).");
@@ -22070,14 +22220,14 @@ function runOkfValidate(location, opts = {}, dir = cwd()) {
22070
22220
  }
22071
22221
 
22072
22222
  // src/services/integrations.ts
22073
- import matter20 from "gray-matter";
22223
+ import matter21 from "gray-matter";
22074
22224
  import { parse as parseYaml19, stringify as stringifyYaml10 } from "yaml";
22075
22225
 
22076
22226
  // src/core/work-item-write.ts
22077
22227
  import fs9 from "fs";
22078
22228
  import path13 from "path";
22079
22229
  import crypto2 from "crypto";
22080
- import matter19 from "gray-matter";
22230
+ import matter20 from "gray-matter";
22081
22231
  var WORK_ITEMS_DIR3 = "knowledge/delivery/work-items";
22082
22232
  var WorkItemWriteError = class extends Error {
22083
22233
  constructor(code, message) {
@@ -22111,7 +22261,7 @@ function nextWorkItemId2(dir) {
22111
22261
  walk2(wiDir);
22112
22262
  return `WI-${String(max + 1).padStart(3, "0")}`;
22113
22263
  }
22114
- function atomicWrite5(filePath, content) {
22264
+ function atomicWrite4(filePath, content) {
22115
22265
  fs9.mkdirSync(path13.dirname(filePath), { recursive: true });
22116
22266
  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
22117
22267
  fs9.writeFileSync(tmp, content, "utf-8");
@@ -22181,7 +22331,7 @@ function ensureH1(body, title) {
22181
22331
  ${trimmed}`;
22182
22332
  }
22183
22333
  function serialize3(data, body) {
22184
- return matter19.stringify(`
22334
+ return matter20.stringify(`
22185
22335
  ${body.trim()}
22186
22336
  `, data);
22187
22337
  }
@@ -22250,7 +22400,7 @@ function createWorkItem(dir, opts) {
22250
22400
  const filePath = join(dir, relPath);
22251
22401
  if (exists(filePath)) throw new WorkItemWriteError("INVALID_INPUT", `Work Item file already exists: ${relPath}`);
22252
22402
  const raw = serialize3(data, body);
22253
- atomicWrite5(filePath, raw);
22403
+ atomicWrite4(filePath, raw);
22254
22404
  return { id, path: relPath, revision: revisionOf(raw) };
22255
22405
  }
22256
22406
 
@@ -23258,7 +23408,7 @@ function findLinkedWorkItem(dir, integrationId, externalId) {
23258
23408
  for (const art of discoverWorkItems(dir)) {
23259
23409
  let data;
23260
23410
  try {
23261
- data = matter20(readFile(art.filePath)).data;
23411
+ data = matter21(readFile(art.filePath)).data;
23262
23412
  } catch {
23263
23413
  continue;
23264
23414
  }
@@ -23914,7 +24064,7 @@ function runAssetsUpdate(kind, opts = {}) {
23914
24064
  // src/commands/ready.ts
23915
24065
  import fs11 from "fs";
23916
24066
  import path14 from "path";
23917
- import matter21 from "gray-matter";
24067
+ import matter22 from "gray-matter";
23918
24068
  function validateReadiness(content, frontmatter2) {
23919
24069
  const warnings = [];
23920
24070
  const body = content.replace(/^---[\s\S]*?---/, "").trim();
@@ -23968,11 +24118,11 @@ function isResolvedSection(text2) {
23968
24118
  }
23969
24119
  function transitionToReady(filePath) {
23970
24120
  const raw = readFile(filePath);
23971
- const { data, content } = matter21(raw);
24121
+ const { data, content } = matter22(raw);
23972
24122
  const today3 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
23973
24123
  data.status = "ready";
23974
24124
  data.ready_at = today3;
23975
- const newContent = matter21.stringify(content, data);
24125
+ const newContent = matter22.stringify(content, data);
23976
24126
  const posix2 = filePath.replace(/\\/g, "/");
23977
24127
  let newPath = filePath;
23978
24128
  if (posix2.includes("/work-items/draft/")) {
@@ -24012,7 +24162,7 @@ async function runReady(id, opts = {}) {
24012
24162
  process.exit(1);
24013
24163
  }
24014
24164
  const raw = readFile(wi.filePath);
24015
- const { data } = matter21(raw);
24165
+ const { data } = matter22(raw);
24016
24166
  const source2 = parseWorkItemSource(data);
24017
24167
  const warnings = validateReadiness(raw, data);
24018
24168
  log.info(`Work Item found:`);
@@ -24188,10 +24338,10 @@ async function runAdmin(opts = {}) {
24188
24338
  // src/core/work-item-import.ts
24189
24339
  import crypto3 from "crypto";
24190
24340
  import fs12 from "fs";
24191
- import matter23 from "gray-matter";
24341
+ import matter24 from "gray-matter";
24192
24342
 
24193
24343
  // src/core/work-items.ts
24194
- import matter22 from "gray-matter";
24344
+ import matter23 from "gray-matter";
24195
24345
  function computeRefinementStatus(wi) {
24196
24346
  const aspects = {
24197
24347
  outcome: Boolean(wi.currentBehavior?.trim() || wi.targetBehavior?.trim()),
@@ -24230,7 +24380,7 @@ function getWorkItem(dir, workItemId) {
24230
24380
  const match = artifacts.find((a) => (a.id || a.title) === workItemId);
24231
24381
  if (!match) throw new WorkItemNotFoundError(workItemId);
24232
24382
  const base = toListItem(match);
24233
- const body = readBody(match.filePath);
24383
+ const body = readBody2(match.filePath);
24234
24384
  const sections = splitSections(body);
24235
24385
  const fm2 = match.rawFrontmatter;
24236
24386
  const knowledge = discoverKnowledge(dir).filter((a) => !a.isWorkItem);
@@ -24324,10 +24474,10 @@ function parseOriginalSnapshot(fm2) {
24324
24474
  updated_at: typeof o.updated_at === "string" ? o.updated_at : void 0
24325
24475
  };
24326
24476
  }
24327
- function readBody(filePath) {
24477
+ function readBody2(filePath) {
24328
24478
  try {
24329
24479
  const raw = readFile(filePath);
24330
- return matter22(raw).content;
24480
+ return matter23(raw).content;
24331
24481
  } catch {
24332
24482
  return "";
24333
24483
  }
@@ -24786,7 +24936,7 @@ function detectFormat(raw) {
24786
24936
  if (!trimmed) throw new ImportError("EMPTY_INPUT", "Import content is empty.");
24787
24937
  if (trimmed.startsWith("---")) {
24788
24938
  try {
24789
- const { data } = matter23(trimmed);
24939
+ const { data } = matter24(trimmed);
24790
24940
  if (data && typeof data === "object" && Object.keys(data).length > 0) {
24791
24941
  const d = data;
24792
24942
  if (d.type === "work-item" || d.id && typeof d.id === "string" && /^WI-\d+/.test(d.id)) {
@@ -24808,7 +24958,7 @@ function parseContent(raw) {
24808
24958
  let bodyText = trimmed;
24809
24959
  if (format === "kaddo-frontmatter" || format === "markdown-frontmatter") {
24810
24960
  try {
24811
- const parsed = matter23(trimmed);
24961
+ const parsed = matter24(trimmed);
24812
24962
  frontmatterFields = parsed.data ?? {};
24813
24963
  bodyText = parsed.content.trim();
24814
24964
  } catch {
@@ -24905,7 +25055,7 @@ function findDuplicateByHash(dir, hash) {
24905
25055
  const raw = readFile(item.filePath);
24906
25056
  if (!raw) continue;
24907
25057
  try {
24908
- const { data } = matter23(raw);
25058
+ const { data } = matter24(raw);
24909
25059
  const source2 = data?.source;
24910
25060
  if (source2 && typeof source2 === "object" && !Array.isArray(source2)) {
24911
25061
  const s = source2;
@@ -25146,7 +25296,7 @@ ${report.handoff}
25146
25296
  }
25147
25297
 
25148
25298
  // src/commands/verify.ts
25149
- import matter24 from "gray-matter";
25299
+ import matter25 from "gray-matter";
25150
25300
 
25151
25301
  // src/core/implementation-evidence.ts
25152
25302
  var WorkItemNotInProgressError = class extends Error {
@@ -25423,7 +25573,7 @@ async function runVerify(workItemId, opts = {}) {
25423
25573
  }
25424
25574
  const changedPaths = await getModifiedFiles("head");
25425
25575
  const raw = readFile(match.filePath);
25426
- const parsed = matter24(raw);
25576
+ const parsed = matter25(raw);
25427
25577
  const fm2 = parsed.data;
25428
25578
  const acs = extractACsFromBody(parsed.content);
25429
25579
  const existingEvidence = fm2.implementation_evidence;
@@ -25541,13 +25691,13 @@ async function runVerify(workItemId, opts = {}) {
25541
25691
  if (shouldPersist) {
25542
25692
  const filePath = match.filePath;
25543
25693
  const wiRaw = readFile(filePath);
25544
- const wiParsed = matter24(wiRaw);
25694
+ const wiParsed = matter25(wiRaw);
25545
25695
  const data = wiParsed.data;
25546
25696
  data.implementation_evidence = verification.implementationEvidence;
25547
25697
  data.implementation_status = verification.implementationStatus;
25548
25698
  data.validation_status = verification.validationStatus;
25549
25699
  data.verified_at = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
25550
- const newRaw = matter24.stringify(wiParsed.content, data);
25700
+ const newRaw = matter25.stringify(wiParsed.content, data);
25551
25701
  writeFile(filePath, newRaw);
25552
25702
  log.success("Work Item frontmatter updated with verification evidence.");
25553
25703
  }
@@ -25825,7 +25975,7 @@ function runTelemetryDisable() {
25825
25975
  }
25826
25976
 
25827
25977
  // src/core/initiative-write.ts
25828
- import matter25 from "gray-matter";
25978
+ import matter26 from "gray-matter";
25829
25979
  var WORK_ITEMS_DIR4 = "knowledge/delivery/work-items";
25830
25980
  var DRAFT_DIR2 = `${WORK_ITEMS_DIR4}/draft`;
25831
25981
  var InitiativeWriteError = class extends Error {
@@ -25937,7 +26087,7 @@ function buildInitiativeContent(id, input) {
25937
26087
  if (input.priority) data.priority = input.priority;
25938
26088
  if (input.source) data.source = input.source;
25939
26089
  if (input.sourceId) data.source_id = input.sourceId;
25940
- return matter25.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
26090
+ return matter26.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
25941
26091
  }
25942
26092
  function createInitiative(dir, input) {
25943
26093
  if (!input.title?.trim()) throw new InitiativeWriteError("Initiative title is required.");
@@ -25961,10 +26111,10 @@ function transitionInitiative(dir, id, to) {
25961
26111
  throw new InitiativeWriteError(`Invalid transition ${ini.status} \u2192 ${to}.`);
25962
26112
  }
25963
26113
  const raw = readFile(ini.filePath);
25964
- const { data, content } = matter25(raw, {});
26114
+ const { data, content } = matter26(raw, {});
25965
26115
  data.status = to;
25966
26116
  if (to === "completed") data.completed_at = today2();
25967
- const newContent = matter25.stringify(content, data);
26117
+ const newContent = matter26.stringify(content, data);
25968
26118
  writeFile(ini.filePath, newContent);
25969
26119
  const updated = parseInitiative(dir, ini.filePath, newContent);
25970
26120
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after transition.");
@@ -26033,7 +26183,7 @@ function buildWorkItemContent(wiId, iniId, candidate) {
26033
26183
  "_What did we learn? Update after completion._",
26034
26184
  ""
26035
26185
  ].join("\n");
26036
- return matter25.stringify("\n" + body, data);
26186
+ return matter26.stringify("\n" + body, data);
26037
26187
  }
26038
26188
  function materializeCandidate(dir, id, candidateId) {
26039
26189
  const ini = getInitiative(dir, id);
@@ -26050,13 +26200,13 @@ function materializeCandidate(dir, id, candidateId) {
26050
26200
  ensureDir(join(dir, DRAFT_DIR2));
26051
26201
  writeFile(join(dir, DRAFT_DIR2, fileName), buildWorkItemContent(wiId, ini.id, candidate));
26052
26202
  const raw = readFile(ini.filePath);
26053
- const { data, content } = matter25(raw, {});
26203
+ const { data, content } = matter26(raw, {});
26054
26204
  const cands = Array.isArray(data.candidates) ? data.candidates : [];
26055
26205
  for (const c of cands) {
26056
26206
  if (c && typeof c === "object" && String(c.id) === candidateId) c.materialized_as = wiId;
26057
26207
  }
26058
26208
  data.candidates = cands;
26059
- const newContent = matter25.stringify(content, data);
26209
+ const newContent = matter26.stringify(content, data);
26060
26210
  writeFile(ini.filePath, newContent);
26061
26211
  const updated = parseInitiative(dir, ini.filePath, newContent);
26062
26212
  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
@@ -26462,7 +26612,7 @@ deprecationRunbookCmd.command("context <planId> <targetId>").description("Show b
26462
26612
  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
26613
  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
26614
  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()));
26615
+ 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
26616
  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
26617
  var integrationsCmd = program.command("integrations").description("Connect Kaddo to external work systems (read-first; import requires human confirmation)");
26468
26618
  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.1",
4
4
  "description": "Knowledge Driven Development toolkit",
5
5
  "license": "MIT",
6
6
  "repository": {