@kal-elsam/kairo-runtime 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Pi, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/scripts/cockpit-smoke.mjs

@@ -26,7 +26,8 @@ const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const require = createRequire(import.meta.url);
 const pkg = require(join(root, "package.json"));
 
-assert.equal(pkg.version, "0.11.0");
+assert.match(pkg.version, /^\d+\.\d+\.\d+$/);
+assert.equal(pkg.name, "@kal-elsam/kairo-runtime");
 assert.ok(pkg.dependencies["ansi-escapes"]);
 
 assert.equal(resolveLayoutMode({ columns: 120, rows: 40 }), LAYOUT_MODES.WIDE);

package/src/global/ink/cockpit-control-center.js

@@ -11,6 +11,7 @@ import {
   formatResourceAdviceLines
 } from "./system-resources-display.js";
 import { formatEcosystemUpdateLines } from "./ecosystem-updates-display.js";
+import { formatObsidianVaultLines } from "./obsidian-vault-display.js";
 
 const HERMES_WIDE_SESSION_LIMIT = 3;
 const HERMES_TITLE_MAX = 48;
@@ -21,6 +22,7 @@ export {
   formatResourceAdviceLines
 } from "./system-resources-display.js";
 export { formatEcosystemUpdateLines } from "./ecosystem-updates-display.js";
+export { formatObsidianVaultLines } from "./obsidian-vault-display.js";
 
 export function buildControlCenterModel({
   projectName = "project",
@@ -192,7 +194,8 @@ function formatCompanionOverlay(companion, layoutMode = LAYOUT_MODES.COMPACT) {
       ...formatHermesActivityLines(companion.signals?.hermes?.activity, layoutMode),
       ...formatSystemResourcesLines(companion.signals?.system?.resources, layoutMode),
       ...formatResourceAdviceLines(companion.signals?.system?.advice, layoutMode),
-      ...formatEcosystemUpdateLines(companion.signals?.ecosystem?.updates, layoutMode)
+      ...formatEcosystemUpdateLines(companion.signals?.ecosystem?.updates, layoutMode),
+      ...formatObsidianVaultLines(companion.signals?.obsidian?.vault, layoutMode)
     ],
     links: companion.links ?? [],
     error: companion.error ?? null

package/src/global/ink/obsidian-vault-display.js

@@ -0,0 +1,37 @@
+import { LAYOUT_MODES } from "./layout.js";
+
+/** Display-only Obsidian vault lines — never shows paths, write CTAs, or sync controls. */
+export function formatObsidianVaultLines(status, layoutMode = LAYOUT_MODES.COMPACT) {
+  if (status == null || typeof status !== "object") return ["Obsidian · unavailable"];
+  const state = typeof status.state === "string" && status.state ? status.state : "error";
+  const notes = typeof status.noteCount === "number" && Number.isFinite(status.noteCount)
+    ? status.noteCount
+    : 0;
+  const pending = typeof status.pendingProposals === "number" && status.pendingProposals > 0
+    ? status.pendingProposals
+    : 0;
+
+  if (state === "unconfigured") return ["Obsidian · unconfigured"];
+  if (state === "missing") return ["Obsidian · missing"];
+  if (state !== "available" && state !== "partial") {
+    return [`Obsidian · ${state}`];
+  }
+
+  const head = state === "partial"
+    ? `Obsidian · partial · ${notes} notes`
+    : `Obsidian · ${notes} notes`;
+  const lines = [head];
+  if (layoutMode === LAYOUT_MODES.MINIMAL) return lines;
+
+  if (pending > 0) lines.push(`  · pending · ${pending}`);
+  else if (layoutMode === LAYOUT_MODES.COMPACT) lines.push("  · no auto-sync");
+
+  if (layoutMode === LAYOUT_MODES.WIDE) {
+    const pub = typeof status.lastPublishAt === "string" && status.lastPublishAt
+      ? status.lastPublishAt.slice(0, 19)
+      : "never";
+    lines.push(`  · last publish · ${pub}`);
+    if (pending === 0) lines.push("  · no auto-sync");
+  }
+  return lines;
+}

package/src/global/observability/build-companion-snapshot.js

@@ -7,6 +7,11 @@ import { loadHermesActivity as defaultHermesActivity } from "./hermes-activity.j
 import { loadSystemResources as defaultSystemResources } from "./system-resources.js";
 import { recommendSystemResources } from "./resource-advisor.js";
 import { loadEcosystemUpdates as defaultEcosystemUpdates } from "./ecosystem-updates.js";
+import {
+  emptyObsidianVaultStatus,
+  loadObsidianVaultStatus as defaultObsidianVault,
+  summarizeObsidianVaultStatus
+} from "./obsidian-status.js";
 import { getObservabilityProbe, registerObservabilityProbe } from "./probe-registry.js";
 
 export const SOFT_LINK_WINDOW_MS = 60 * 60 * 1000;
@@ -179,7 +184,8 @@ function emptyCompanion(error = null) {
       graphify: { state: "error", error: null, diagnostics: [], graphStatus: null },
       hermes: { activity: emptyHermesActivity() },
       system: { resources: emptySystemResources(), advice: { recommendations: [], deepScan: false } },
-      ecosystem: { updates: emptyEcosystemUpdates() }
+      ecosystem: { updates: emptyEcosystemUpdates() },
+      obsidian: { vault: emptyObsidianVaultStatus() }
     },
     engram: { status: "error", binary: null },
     links: [], alertsCount: null,
@@ -199,6 +205,7 @@ export async function buildCompanionSnapshot({
   loadHermesActivity = defaultHermesActivity,
   loadSystemResources = defaultSystemResources,
   loadEcosystemUpdates = defaultEcosystemUpdates,
+  loadObsidianVaultStatus = defaultObsidianVault,
   resourceDeepScan = false,
   observabilityContext = {}
 } = {}) {
@@ -249,6 +256,19 @@ export async function buildCompanionSnapshot({
       ecosystemUpdates = emptyEcosystemUpdates();
     }
 
+    let obsidianVault = emptyObsidianVaultStatus();
+    try {
+      obsidianVault = summarizeObsidianVaultStatus(
+        await loadObsidianVaultStatus({
+          vaultPath: observabilityContext?.obsidianVaultPath ?? observabilityContext?.vaultPath ?? null,
+          lastPublishAt: observabilityContext?.obsidianLastPublishAt ?? null,
+          pendingProposals: observabilityContext?.obsidianPendingProposals ?? 0
+        })
+      );
+    } catch {
+      obsidianVault = emptyObsidianVaultStatus();
+    }
+
     const reviewList = Array.isArray(reviews)
       ? reviews
       : (typeof loadReviews === "function" ? await loadReviews() : []);
@@ -259,7 +279,8 @@ export async function buildCompanionSnapshot({
       ...summarizeCompanionProbes(obs?.probes ?? []),
       hermes: { activity: hermesActivity },
       system: { resources: systemResources, advice: systemAdvice },
-      ecosystem: { updates: ecosystemUpdates }
+      ecosystem: { updates: ecosystemUpdates },
+      obsidian: { vault: obsidianVault }
     };
     const links = [];
     for (const review of reviewList ?? []) {

package/src/global/observability/index.js

@@ -68,6 +68,45 @@ export {
   parseHermesUpdateCheck,
   loadEcosystemUpdates
 } from "./ecosystem-updates.js";
+export {
+  KAIRO_VAULT_SUBDIR,
+  EXCLUDED_DIR_NAMES,
+  normalizeVaultPath,
+  isExcludedDirName,
+  isSecretBasename,
+  isAllowedKairoNoteName,
+  assertInsideKairoRoot,
+  resolveKairoNotePath,
+  inspectObsidianVault
+} from "./obsidian-vault.js";
+export {
+  formatKnowledgeFrontmatter,
+  renderDecisionMarkdown,
+  renderArchitectureMarkdown,
+  buildObsidianKnowledgePreview,
+  loadObsidianKnowledgePreview
+} from "./obsidian-knowledge-preview.js";
+export {
+  KAIRO_MANAGED_FRONTMATTER,
+  BACKUP_DIR_NAME,
+  hasConsent,
+  classifyNoteWrite,
+  planObsidianPublish,
+  publishObsidianProposals
+} from "./obsidian-publisher.js";
+export {
+  KAIRO_VIEW_KINDS,
+  parseKnowledgeFrontmatter,
+  extractWikilinks,
+  buildObsidianKnowledgeViews,
+  buildKnowledgeIndexProposals,
+  loadObsidianKnowledgeViews
+} from "./obsidian-knowledge-views.js";
+export {
+  emptyObsidianVaultStatus,
+  summarizeObsidianVaultStatus,
+  loadObsidianVaultStatus
+} from "./obsidian-status.js";
 export {
   SOFT_LINK_WINDOW_MS,
   parseCompanionTimestamp,

package/src/global/observability/obsidian-knowledge-preview.js

@@ -0,0 +1,214 @@
+import { resolveKairoNotePath } from "./obsidian-vault.js";
+
+const MAX_PROPOSALS = 40;
+const TITLE_MAX = 80;
+
+function envelope(partial = {}) {
+  return {
+    state: "error",
+    proposals: [],
+    diagnostics: [],
+    error: null,
+    generatedAt: null,
+    ...partial
+  };
+}
+
+function scrubTitle(raw, fallback = "untitled") {
+  const text = String(raw ?? "")
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/[\[\]#|\\/]+/g, " ")
+    .trim()
+    .slice(0, TITLE_MAX);
+  return text || fallback;
+}
+
+function slugify(title) {
+  return scrubTitle(title, "note")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48) || "note";
+}
+
+/** Stable YAML-ish frontmatter — no nested objects; values are scalars only. */
+export function formatKnowledgeFrontmatter(fields = {}) {
+  const lines = ["---"];
+  for (const key of Object.keys(fields).sort()) {
+    const value = fields[key];
+    if (value == null || value === "") continue;
+    const safe = String(value).replace(/[\r\n]+/g, " ").replace(/"/g, "'");
+    lines.push(`${key}: "${safe}"`);
+  }
+  lines.push("---", "");
+  return lines.join("\n");
+}
+
+export function renderDecisionMarkdown(entry, { generatedAt } = {}) {
+  const title = scrubTitle(entry?.title ?? entry?.id, "decision");
+  const id = scrubTitle(entry?.id ?? slugify(title), slugify(title));
+  const body = String(entry?.body ?? entry?.content ?? "").trim();
+  const fm = formatKnowledgeFrontmatter({
+    kairo_kind: "decision",
+    kairo_id: id,
+    source: "engram-export",
+    generated_at: generatedAt ?? null,
+    title
+  });
+  const wiki = `[[decisions/${slugify(title)}]]`;
+  return {
+    relativePath: `decisions/${slugify(title)}.md`,
+    title,
+    provenance: { system: "engram", kind: "decision", id },
+    markdown: `${fm}# ${title}\n\n${body || "_No body provided._"}\n\n---\nSource: Engram export · ${wiki}\n`
+  };
+}
+
+export function renderArchitectureMarkdown(entry, { generatedAt } = {}) {
+  const title = scrubTitle(entry?.title ?? entry?.name ?? entry?.id, "architecture");
+  const id = scrubTitle(entry?.id ?? slugify(title), slugify(title));
+  const detail = String(entry?.detail ?? entry?.summary ?? "").trim();
+  const links = Array.isArray(entry?.related)
+    ? entry.related.map((r) => `- [[architecture/${slugify(r)}]]`).join("\n")
+    : "";
+  const fm = formatKnowledgeFrontmatter({
+    kairo_kind: "architecture",
+    kairo_id: id,
+    source: "graphify-export",
+    generated_at: generatedAt ?? null,
+    title
+  });
+  return {
+    relativePath: `architecture/${slugify(title)}.md`,
+    title,
+    provenance: { system: "graphify", kind: "architecture", id },
+    markdown: `${fm}# ${title}\n\n${detail || "_No summary provided._"}\n${links ? `\n## Related\n${links}\n` : ""}`
+  };
+}
+
+/**
+ * Pure composer — accepts already-exported records only.
+ * Never opens Engram/Graphify internal DBs or vault files.
+ */
+export function buildObsidianKnowledgePreview({
+  decisions = [],
+  architecture = [],
+  generatedAt = new Date().toISOString(),
+  maxProposals = MAX_PROPOSALS,
+  kairoRoot = "/virtual/Kairo"
+} = {}) {
+  const diagnostics = [];
+  const proposals = [];
+
+  const push = (draft) => {
+    if (proposals.length >= maxProposals) return;
+    const gate = resolveKairoNotePath(kairoRoot, draft.relativePath);
+    if (!gate.ok) {
+      diagnostics.push(`rejected ${draft.relativePath}: ${gate.reason}`);
+      return;
+    }
+    proposals.push({
+      relativePath: draft.relativePath,
+      title: draft.title,
+      markdown: draft.markdown,
+      provenance: draft.provenance,
+      absolutePath: gate.path
+    });
+  };
+
+  for (const entry of decisions ?? []) {
+    if (entry == null || typeof entry !== "object") {
+      diagnostics.push("skipped malformed decision");
+      continue;
+    }
+    push(renderDecisionMarkdown(entry, { generatedAt }));
+  }
+  for (const entry of architecture ?? []) {
+    if (entry == null || typeof entry !== "object") {
+      diagnostics.push("skipped malformed architecture");
+      continue;
+    }
+    push(renderArchitectureMarkdown(entry, { generatedAt }));
+  }
+
+  if (proposals.length === 0 && diagnostics.length === 0) {
+    return envelope({
+      state: "empty",
+      proposals: [],
+      diagnostics: ["no export records provided"],
+      generatedAt,
+      error: null
+    });
+  }
+
+  return envelope({
+    state: proposals.length > 0 ? "available" : "partial",
+    proposals,
+    diagnostics,
+    generatedAt,
+    error: null
+  });
+}
+
+/**
+ * Load preview via injectable export adapters — never vault writes.
+ * Adapters must return plain arrays of records (already exported).
+ */
+export async function loadObsidianKnowledgePreview({
+  loadEngramExport = null,
+  loadGraphifyExport = null,
+  kairoRoot = "/virtual/Kairo",
+  generatedAt = new Date().toISOString(),
+  maxProposals = MAX_PROPOSALS
+} = {}) {
+  const diagnostics = [];
+  let decisions = [];
+  let architecture = [];
+
+  if (typeof loadEngramExport === "function") {
+    try {
+      const raw = await loadEngramExport();
+      decisions = Array.isArray(raw) ? raw : Array.isArray(raw?.decisions) ? raw.decisions : [];
+      if (!Array.isArray(raw) && raw != null && !Array.isArray(raw?.decisions)) {
+        diagnostics.push("engram export shape unrecognized");
+      }
+    } catch (err) {
+      diagnostics.push(`engram export failed: ${String(err?.message ?? err)}`);
+    }
+  } else {
+    diagnostics.push("engram export adapter not provided");
+  }
+
+  if (typeof loadGraphifyExport === "function") {
+    try {
+      const raw = await loadGraphifyExport();
+      architecture = Array.isArray(raw)
+        ? raw
+        : Array.isArray(raw?.architecture)
+          ? raw.architecture
+          : Array.isArray(raw?.communities)
+            ? raw.communities
+            : [];
+      if (
+        !Array.isArray(raw)
+        && raw != null
+        && !Array.isArray(raw?.architecture)
+        && !Array.isArray(raw?.communities)
+      ) {
+        diagnostics.push("graphify export shape unrecognized");
+      }
+    } catch (err) {
+      diagnostics.push(`graphify export failed: ${String(err?.message ?? err)}`);
+    }
+  } else {
+    diagnostics.push("graphify export adapter not provided");
+  }
+
+  const preview = buildObsidianKnowledgePreview({
+    decisions, architecture, generatedAt, maxProposals, kairoRoot
+  });
+  return {
+    ...preview,
+    diagnostics: [...diagnostics, ...(preview.diagnostics ?? [])]
+  };
+}

package/src/global/observability/obsidian-knowledge-views.js

@@ -0,0 +1,227 @@
+import { resolveKairoNotePath } from "./obsidian-vault.js";
+import { formatKnowledgeFrontmatter } from "./obsidian-knowledge-preview.js";
+
+/** Canonical view folders / kairo_kind values under Kairo/. */
+export const KAIRO_VIEW_KINDS = Object.freeze([
+  "projects", "decisions", "architecture", "sessions", "reviews"
+]);
+
+const KIND_SET = new Set(KAIRO_VIEW_KINDS);
+const MAX_INDEX_LINKS = 80;
+
+function envelope(partial = {}) {
+  return { state: "error", views: emptyViews(), links: [], diagnostics: [], error: null, ...partial };
+}
+
+function emptyViews() {
+  return Object.fromEntries(KAIRO_VIEW_KINDS.map((k) => [k, []]));
+}
+
+/** Parse simple `key: "value"` frontmatter between leading --- fences. */
+export function parseKnowledgeFrontmatter(markdown) {
+  const text = String(markdown ?? "");
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!m) return { fields: {}, body: text, hasFrontmatter: false };
+  const fields = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([A-Za-z0-9_]+):\s*"(.*)"\s*$/);
+    if (kv) fields[kv[1]] = kv[2];
+  }
+  return { fields, body: text.slice(m[0].length), hasFrontmatter: true };
+}
+
+/** Extract `[[target]]` / `[[target|alias]]` wikilinks — display-only graph edges. */
+export function extractWikilinks(markdown) {
+  const links = [];
+  const re = /\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|[^\]]+)?\]\]/g;
+  let match;
+  const text = String(markdown ?? "");
+  while ((match = re.exec(text)) != null) {
+    const target = match[1].trim().replace(/\\/g, "/");
+    if (target && !target.includes("..")) links.push(target);
+  }
+  return links;
+}
+
+function inferKind(relativePath, fields) {
+  const kind = fields.kairo_kind;
+  if (typeof kind === "string" && KIND_SET.has(kind)) return kind;
+  const head = String(relativePath ?? "").split(/[/\\]/)[0];
+  return KIND_SET.has(head) ? head : null;
+}
+
+function normalizeWikiTarget(target) {
+  const t = String(target).replace(/\.md$/i, "");
+  return t.startsWith("/") ? t.slice(1) : t;
+}
+
+/**
+ * Read-only index of Kairo notes into view buckets + wikilink edges.
+ * `contentsByPath` is optional utf8 map; missing content → title-only entries.
+ */
+export function buildObsidianKnowledgeViews({
+  notes = [],
+  contentsByPath = {},
+  kairoRoot = "/virtual/Kairo"
+} = {}) {
+  const views = emptyViews();
+  const links = [];
+  const diagnostics = [];
+  const byPath = new Set();
+
+  for (const note of notes ?? []) {
+    if (note == null || typeof note !== "object") {
+      diagnostics.push("skipped malformed note");
+      continue;
+    }
+    const relativePath = String(note.relativePath ?? "");
+    const gate = resolveKairoNotePath(kairoRoot, relativePath);
+    if (!gate.ok) {
+      diagnostics.push(`skipped ${relativePath || "?"}: ${gate.reason}`);
+      continue;
+    }
+    const markdown = contentsByPath[relativePath];
+    const parsed = typeof markdown === "string"
+      ? parseKnowledgeFrontmatter(markdown)
+      : { fields: {}, body: "", hasFrontmatter: false };
+    const kind = inferKind(relativePath, parsed.fields);
+    if (!kind) {
+      diagnostics.push(`unclassified ${relativePath}`);
+      continue;
+    }
+    const title = parsed.fields.title
+      || note.title
+      || relativePath.replace(/\.md$/i, "").split("/").pop();
+    const entry = {
+      relativePath,
+      title: String(title),
+      kairoId: parsed.fields.kairo_id ?? null,
+      kind,
+      wikiPath: relativePath.replace(/\.md$/i, "")
+    };
+    views[kind].push(entry);
+    byPath.add(entry.wikiPath);
+
+    if (typeof markdown === "string") {
+      for (const target of extractWikilinks(markdown)) {
+        links.push({
+          from: entry.wikiPath,
+          to: normalizeWikiTarget(target),
+          kind: entry.kind
+        });
+      }
+    }
+  }
+
+  for (const kind of KAIRO_VIEW_KINDS) {
+    views[kind].sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  }
+  links.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+
+  const total = KAIRO_VIEW_KINDS.reduce((n, k) => n + views[k].length, 0);
+  return envelope({
+    state: total > 0 ? "available" : "empty",
+    views,
+    links,
+    diagnostics,
+    error: null,
+    resolvedTargets: [...byPath].sort()
+  });
+}
+
+/** Build index-note *proposals* only — publish via Slice 03 with consent. */
+export function buildKnowledgeIndexProposals(viewsResult, {
+  generatedAt = new Date().toISOString(),
+  kairoRoot = "/virtual/Kairo"
+} = {}) {
+  const views = viewsResult?.views ?? emptyViews();
+  const proposals = [];
+  const diagnostics = [];
+
+  for (const kind of KAIRO_VIEW_KINDS) {
+    const entries = views[kind] ?? [];
+    const lines = entries.slice(0, MAX_INDEX_LINKS).map((e) => `- [[${e.wikiPath}|${e.title}]]`);
+    const fm = formatKnowledgeFrontmatter({
+      kairo_kind: kind,
+      kairo_id: `index-${kind}`,
+      source: "kairo-index",
+      generated_at: generatedAt,
+      title: `${kind} index`
+    });
+    const markdown = `${fm}# ${kind}\n\n${lines.length ? lines.join("\n") : "_No notes yet._"}\n`;
+    const relativePath = `${kind}/index.md`;
+    const gate = resolveKairoNotePath(kairoRoot, relativePath);
+    if (!gate.ok) {
+      diagnostics.push(`index ${kind}: ${gate.reason}`);
+      continue;
+    }
+    proposals.push({
+      relativePath,
+      title: `${kind} index`,
+      markdown,
+      provenance: { system: "kairo", kind: "index", id: kind },
+      absolutePath: gate.path
+    });
+  }
+
+  return {
+    state: proposals.length ? "available" : "empty",
+    proposals,
+    diagnostics,
+    generatedAt
+  };
+}
+
+/**
+ * Convenience: inspect notes + optional content loader → views.
+ * Never writes; `readNote` must be injectable (tests / CLI).
+ */
+export async function loadObsidianKnowledgeViews({
+  inspectVault,
+  vaultPath,
+  readNote = null,
+  kairoRoot = null
+} = {}) {
+  if (typeof inspectVault !== "function") {
+    return envelope({ error: "inspectVault required", diagnostics: ["inspectVault required"] });
+  }
+  let inspected;
+  try {
+    inspected = await inspectVault({ vaultPath });
+  } catch (err) {
+    return envelope({
+      error: String(err?.message ?? err),
+      diagnostics: [`inspect failed: ${String(err?.message ?? err)}`]
+    });
+  }
+  const root = kairoRoot ?? inspected?.kairoRoot;
+  if (!root) {
+    return envelope({
+      state: inspected?.state ?? "error",
+      error: inspected?.error ?? "kairoRoot missing",
+      diagnostics: inspected?.diagnostics ?? ["kairoRoot missing"]
+    });
+  }
+  const contentsByPath = {};
+  if (typeof readNote === "function") {
+    for (const note of inspected.notes ?? []) {
+      try {
+        const text = await readNote(note.relativePath, root);
+        if (typeof text === "string") contentsByPath[note.relativePath] = text;
+      } catch {
+        /* fail-soft: title-only entry */
+      }
+    }
+  }
+  const built = buildObsidianKnowledgeViews({
+    notes: inspected.notes ?? [],
+    contentsByPath,
+    kairoRoot: root
+  });
+  return {
+    ...built,
+    diagnostics: [...(inspected.diagnostics ?? []), ...built.diagnostics],
+    vaultPath: inspected.vaultPath ?? vaultPath ?? null,
+    kairoRoot: root
+  };
+}

package/src/global/observability/obsidian-publisher.js

@@ -0,0 +1,181 @@
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import {
+  copyFile, lstat, mkdir, readFile, realpath, rename, rm, writeFile
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { hashBuffer } from "../../hash.js";
+import {
+  assertInsideKairoRoot, isAllowedKairoNoteName, resolveKairoNotePath
+} from "./obsidian-vault.js";
+
+/** Slice 02 frontmatter marker — managed notes may be updated; manual notes refused. */
+export const KAIRO_MANAGED_FRONTMATTER = /^kairo_kind:\s*"/m;
+export const BACKUP_DIR_NAME = ".kairo-backups";
+
+const envelope = (partial = {}) => ({
+  state: "error", dryRun: false, results: [], diagnostics: [], error: null, ...partial
+});
+
+export const hasConsent = ({ yes = false, confirm = false } = {}) =>
+  yes === true || confirm === true;
+
+export function classifyNoteWrite(existingMarkdown, proposedMarkdown) {
+  if (existingMarkdown === proposedMarkdown) return { action: "skip", reason: "identical" };
+  if (KAIRO_MANAGED_FRONTMATTER.test(String(existingMarkdown ?? ""))) {
+    return { action: "update", reason: "managed" };
+  }
+  return { action: "refuse", reason: "manual content" };
+}
+
+function validateProposal(proposal, kairoRoot) {
+  if (proposal == null || typeof proposal !== "object") return { ok: false, reason: "malformed proposal" };
+  const relativePath = String(proposal.relativePath ?? "");
+  const markdown = proposal.markdown;
+  if (typeof markdown !== "string") return { ok: false, reason: "proposal markdown required" };
+  const base = relativePath.split(/[/\\]/).pop() ?? "";
+  if (!isAllowedKairoNoteName(base)) return { ok: false, reason: "proposal basename not allowed" };
+  const gate = resolveKairoNotePath(kairoRoot, relativePath);
+  if (!gate.ok) return { ok: false, reason: gate.reason };
+  return { ok: true, relativePath, markdown, absolutePath: gate.path };
+}
+
+/** Plan-only: `existingByPath` maps relativePath → utf8 (null = missing). No writes. */
+export function planObsidianPublish(proposals = [], { kairoRoot, existingByPath = {} } = {}) {
+  if (typeof kairoRoot !== "string" || !kairoRoot) {
+    return envelope({ error: "kairoRoot required", diagnostics: ["kairoRoot required"] });
+  }
+  const results = [], diagnostics = [];
+  for (const proposal of proposals) {
+    const v = validateProposal(proposal, kairoRoot);
+    if (!v.ok) {
+      results.push({ relativePath: proposal?.relativePath ?? null, action: "refuse", reason: v.reason });
+      diagnostics.push(v.reason);
+      continue;
+    }
+    const existing = existingByPath[v.relativePath];
+    const cls = existing == null
+      ? { action: "create", reason: "missing" }
+      : classifyNoteWrite(existing, v.markdown);
+    results.push({
+      relativePath: v.relativePath, absolutePath: v.absolutePath,
+      action: cls.action, reason: cls.reason,
+      hash: hashBuffer(Buffer.from(v.markdown, "utf8"))
+    });
+  }
+  return envelope({ state: "planned", dryRun: true, results, diagnostics, error: null });
+}
+
+async function resolveKairoRoot(kairoRoot, { realpathFn = realpath, existsFn = existsSync } = {}) {
+  if (typeof kairoRoot !== "string" || !kairoRoot) return { ok: false, reason: "kairoRoot required" };
+  if (!existsFn(kairoRoot)) return { ok: false, reason: "kairoRoot missing" };
+  try { return { ok: true, path: await realpathFn(kairoRoot) }; }
+  catch { return { ok: false, reason: "kairoRoot unreadable" }; }
+}
+
+async function readExistingMap(proposals, kairoRoot, { readFileFn = readFile, existsFn = existsSync } = {}) {
+  const map = {};
+  for (const proposal of proposals) {
+    const v = validateProposal(proposal, kairoRoot);
+    if (!v.ok) continue;
+    if (!existsFn(v.absolutePath)) { map[v.relativePath] = null; continue; }
+    try { map[v.relativePath] = await readFileFn(v.absolutePath, "utf8"); }
+    catch { map[v.relativePath] = null; }
+  }
+  return map;
+}
+
+async function backupExisting(absolutePath, relativePath, kairoRoot, {
+  copyFileFn = copyFile, mkdirFn = mkdir, nowMs = Date.now()
+} = {}) {
+  const backupGate = resolveKairoNotePath(kairoRoot, join(BACKUP_DIR_NAME, `${relativePath}.${nowMs}.bak`));
+  if (!backupGate.ok) return { ok: false, reason: backupGate.reason };
+  await mkdirFn(dirname(backupGate.path), { recursive: true });
+  await copyFileFn(absolutePath, backupGate.path);
+  return { ok: true, path: backupGate.path };
+}
+
+async function atomicWrite(absolutePath, markdown, kairoRoot, {
+  writeFileFn = writeFile, renameFn = rename, rmFn = rm, mkdirFn = mkdir,
+  lstatFn = lstat, existsFn = existsSync
+} = {}) {
+  const parent = dirname(absolutePath);
+  await mkdirFn(parent, { recursive: true });
+  const parentGate = await assertInsideKairoRoot(parent, kairoRoot, { lstatFn, existsFn });
+  if (!parentGate.ok && !parentGate.missing) throw new Error(parentGate.reason ?? "parent escapes Kairo/");
+  const destGate = await assertInsideKairoRoot(absolutePath, kairoRoot, { lstatFn, existsFn });
+  if (!destGate.ok) throw new Error(destGate.reason);
+  if (destGate.symlink) throw new Error("destination is a symlink; refusing");
+  const tmp = join(parent, `.kairo-write-${randomBytes(12).toString("hex")}.tmp`);
+  try {
+    await writeFileFn(tmp, markdown, { encoding: "utf8", flag: "wx" });
+    await renameFn(tmp, absolutePath);
+  } catch (err) {
+    await rmFn(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+/** Consent-gated publish. dryRun / no consent → plan only. Never deletes notes. */
+export async function publishObsidianProposals({
+  kairoRoot, proposals = [], yes = false, confirm = false, dryRun = false,
+  readFileFn = readFile, writeFileFn = writeFile, renameFn = rename, rmFn = rm,
+  mkdirFn = mkdir, copyFileFn = copyFile, lstatFn = lstat, existsFn = existsSync,
+  realpathFn = realpath, nowMs = Date.now()
+} = {}) {
+  const resolved = await resolveKairoRoot(kairoRoot, { realpathFn, existsFn });
+  if (!resolved.ok) return envelope({ error: resolved.reason, diagnostics: [resolved.reason] });
+  kairoRoot = resolved.path;
+
+  const plan = planObsidianPublish(proposals, {
+    kairoRoot,
+    existingByPath: await readExistingMap(proposals, kairoRoot, { readFileFn, existsFn })
+  });
+  if (dryRun === true || !hasConsent({ yes, confirm })) {
+    const reason = dryRun === true ? null : "consent required: pass yes or confirm";
+    return {
+      ...plan, state: dryRun === true ? "planned" : "blocked", dryRun: true, error: reason,
+      diagnostics: reason ? [...plan.diagnostics, reason] : plan.diagnostics
+    };
+  }
+
+  const results = [], diagnostics = [...plan.diagnostics];
+  const io = { writeFileFn, renameFn, rmFn, mkdirFn, copyFileFn, lstatFn, existsFn, nowMs };
+  for (const step of plan.results) {
+    if (step.action === "refuse" || step.action === "skip") { results.push({ ...step }); continue; }
+    const markdown = proposals.find((p) => p?.relativePath === step.relativePath)?.markdown;
+    if (typeof markdown !== "string") {
+      results.push({ ...step, action: "refuse", reason: "proposal markdown required" });
+      continue;
+    }
+    try {
+      let backupPath = null;
+      if (step.action === "update" && existsFn(step.absolutePath)) {
+        const bak = await backupExisting(step.absolutePath, step.relativePath, kairoRoot, io);
+        if (!bak.ok) {
+          results.push({ ...step, action: "refuse", reason: bak.reason });
+          diagnostics.push(bak.reason);
+          continue;
+        }
+        backupPath = bak.path;
+      }
+      const gate = resolveKairoNotePath(kairoRoot, step.relativePath);
+      if (!gate.ok) { results.push({ ...step, action: "refuse", reason: gate.reason }); continue; }
+      await atomicWrite(gate.path, markdown, kairoRoot, io);
+      results.push({
+        ...step, absolutePath: gate.path, backupPath,
+        action: step.action === "create" ? "created" : "updated"
+      });
+    } catch (err) {
+      const msg = String(err?.message ?? err);
+      results.push({ ...step, action: "error", reason: msg });
+      diagnostics.push(msg);
+    }
+  }
+  const wrote = results.some((r) => r.action === "created" || r.action === "updated");
+  const errored = results.some((r) => r.action === "error");
+  return envelope({
+    state: errored ? "partial" : wrote ? "applied" : "noop",
+    dryRun: false, results, diagnostics, error: null
+  });
+}

package/src/global/observability/obsidian-status.js

@@ -0,0 +1,76 @@
+import { inspectObsidianVault as defaultInspect } from "./obsidian-vault.js";
+
+function envelope(partial = {}) {
+  return {
+    state: "unconfigured",
+    vaultPath: null,
+    kairoRoot: null,
+    noteCount: 0,
+    lastPublishAt: null,
+    pendingProposals: 0,
+    diagnostics: [],
+    error: null,
+    ...partial
+  };
+}
+
+export function emptyObsidianVaultStatus() {
+  return envelope({ state: "error", error: "error" });
+}
+
+export function summarizeObsidianVaultStatus(raw) {
+  if (raw == null || typeof raw !== "object") return emptyObsidianVaultStatus();
+  const noteCount = Array.isArray(raw.notes)
+    ? raw.notes.length
+    : (typeof raw.noteCount === "number" && Number.isFinite(raw.noteCount) ? raw.noteCount : 0);
+  return envelope({
+    state: typeof raw.state === "string" && raw.state ? raw.state : "error",
+    vaultPath: raw.vaultPath ?? null,
+    kairoRoot: raw.kairoRoot ?? null,
+    noteCount,
+    lastPublishAt: typeof raw.lastPublishAt === "string" ? raw.lastPublishAt : null,
+    pendingProposals: typeof raw.pendingProposals === "number" && raw.pendingProposals > 0
+      ? Math.floor(raw.pendingProposals)
+      : 0,
+    diagnostics: Array.isArray(raw.diagnostics) ? raw.diagnostics.map(String) : [],
+    error: raw.error == null ? null : String(raw.error)
+  });
+}
+
+/**
+ * Read-only vault status for Cockpit. No writes / no auto-sync.
+ * Without an absolute vaultPath → unconfigured (never guesses a home vault).
+ */
+export async function loadObsidianVaultStatus({
+  vaultPath = null,
+  lastPublishAt = null,
+  pendingProposals = 0,
+  inspectObsidianVault = defaultInspect
+} = {}) {
+  if (vaultPath == null || vaultPath === "") {
+    return envelope({
+      state: "unconfigured",
+      diagnostics: ["vaultPath not configured"],
+      lastPublishAt,
+      pendingProposals: typeof pendingProposals === "number" ? Math.max(0, Math.floor(pendingProposals)) : 0
+    });
+  }
+  try {
+    const inspected = await inspectObsidianVault({ vaultPath });
+    return summarizeObsidianVaultStatus({
+      ...inspected,
+      noteCount: inspected?.notes?.length ?? 0,
+      lastPublishAt,
+      pendingProposals
+    });
+  } catch (err) {
+    return envelope({
+      state: "error",
+      vaultPath: String(vaultPath),
+      error: String(err?.message ?? err),
+      diagnostics: [String(err?.message ?? err)],
+      lastPublishAt,
+      pendingProposals: typeof pendingProposals === "number" ? Math.max(0, Math.floor(pendingProposals)) : 0
+    });
+  }
+}

package/src/global/observability/obsidian-vault.js

@@ -0,0 +1,259 @@
+import { existsSync } from "node:fs";
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { basename, isAbsolute, join, resolve, sep } from "node:path";
+import { isPathInside } from "../component-paths.js";
+
+/** Obsidian vault subfolder Kairo may read — never the whole vault. */
+export const KAIRO_VAULT_SUBDIR = "Kairo";
+
+/** Directory basenames refused anywhere under the Kairo tree. */
+export const EXCLUDED_DIR_NAMES = Object.freeze([
+  ".obsidian", ".git", ".trash", "attachments", "Attachment", "Assets", "assets"
+]);
+
+const SECRET_BASENAME = /(?:^|\.)(env|secret|secrets|credentials|token|tokens|key|keys|pem|p12|pfx)(?:\.|$)/i;
+const MARKDOWN_EXT = /\.md$/i;
+const MAX_NOTES = 200;
+const MAX_WALK_DEPTH = 8;
+
+function envelope(partial = {}) {
+  return {
+    state: "error",
+    vaultPath: null,
+    kairoRoot: null,
+    notes: [],
+    diagnostics: [],
+    error: null,
+    ...partial
+  };
+}
+
+/** Absolute vault path only — no home expansion, no relative paths. */
+export function normalizeVaultPath(raw) {
+  if (typeof raw !== "string" || !raw.trim()) {
+    return { ok: false, reason: "vaultPath required" };
+  }
+  const trimmed = raw.trim();
+  if (!isAbsolute(trimmed)) {
+    return { ok: false, reason: "vaultPath must be absolute" };
+  }
+  const resolved = resolve(trimmed);
+  if (resolved.includes("\0")) {
+    return { ok: false, reason: "vaultPath invalid" };
+  }
+  return { ok: true, path: resolved };
+}
+
+export function isExcludedDirName(name) {
+  return EXCLUDED_DIR_NAMES.includes(String(name ?? ""));
+}
+
+export function isSecretBasename(name) {
+  return SECRET_BASENAME.test(String(name ?? ""));
+}
+
+export function isAllowedKairoNoteName(name) {
+  const base = basename(String(name ?? ""));
+  if (!MARKDOWN_EXT.test(base)) return false;
+  if (isSecretBasename(base)) return false;
+  if (base.startsWith(".")) return false;
+  return true;
+}
+
+/**
+ * Candidate must resolve inside kairoRoot (realpath). Symlinks that escape fail.
+ * Relative segments with `..` that leave Kairo/ fail before IO when possible.
+ */
+export async function assertInsideKairoRoot(candidatePath, kairoRoot, {
+  lstatFn = lstat,
+  realpathFn = realpath,
+  existsFn = existsSync
+} = {}) {
+  const root = resolve(kairoRoot);
+  const claimed = resolve(candidatePath);
+  if (!isPathInside(root, claimed) && claimed !== root) {
+    return { ok: false, reason: "path escapes Kairo/" };
+  }
+  if (!existsFn(claimed)) {
+    return { ok: true, path: claimed, missing: true };
+  }
+  try {
+    const st = await lstatFn(claimed);
+    if (st.isSymbolicLink()) {
+      const target = await realpathFn(claimed);
+      if (!isPathInside(root, target) && target !== root) {
+        return { ok: false, reason: "symlink escapes Kairo/" };
+      }
+      return { ok: true, path: target, symlink: true };
+    }
+    const real = await realpathFn(claimed);
+    if (!isPathInside(root, real) && real !== root) {
+      return { ok: false, reason: "realpath escapes Kairo/" };
+    }
+    return { ok: true, path: real };
+  } catch {
+    return { ok: false, reason: "path unreadable" };
+  }
+}
+
+async function refuseVaultSymlink(vaultPath, { lstatFn = lstat } = {}) {
+  try {
+    if ((await lstatFn(vaultPath)).isSymbolicLink()) {
+      return "vault root is a symlink; refusing";
+    }
+  } catch {
+    return "vault unreadable";
+  }
+  return null;
+}
+
+/**
+ * Read-only inspect of an Obsidian vault's Kairo/ subtree.
+ * Never writes; never reads Engram/Graphify stores; never opens .obsidian.
+ */
+export async function inspectObsidianVault({
+  vaultPath,
+  lstatFn = lstat,
+  readdirFn = readdir,
+  realpathFn = realpath,
+  existsFn = existsSync,
+  maxNotes = MAX_NOTES
+} = {}) {
+  const norm = normalizeVaultPath(vaultPath);
+  if (!norm.ok) {
+    return envelope({ state: "unavailable", error: norm.reason, diagnostics: [norm.reason] });
+  }
+  const root = norm.path;
+  if (!existsFn(root)) {
+    return envelope({
+      state: "missing", vaultPath: root, error: "vault missing",
+      diagnostics: ["vault path does not exist"]
+    });
+  }
+  const vaultSym = await refuseVaultSymlink(root, { lstatFn });
+  if (vaultSym) {
+    return envelope({
+      state: "error", vaultPath: root, error: vaultSym, diagnostics: [vaultSym]
+    });
+  }
+
+  let vaultReal;
+  try { vaultReal = await realpathFn(root); }
+  catch {
+    return envelope({
+      state: "error", vaultPath: root, error: "vault unreadable",
+      diagnostics: ["vault realpath failed"]
+    });
+  }
+
+  const kairoRoot = join(vaultReal, KAIRO_VAULT_SUBDIR);
+  if (!existsFn(kairoRoot)) {
+    return envelope({
+      state: "partial", vaultPath: vaultReal, kairoRoot,
+      error: null, diagnostics: ["Kairo/ subdirectory missing"]
+    });
+  }
+
+  const kairoGate = await assertInsideKairoRoot(kairoRoot, kairoRoot, {
+    lstatFn, realpathFn, existsFn
+  });
+  if (!kairoGate.ok) {
+    return envelope({
+      state: "error", vaultPath: vaultReal, kairoRoot,
+      error: kairoGate.reason, diagnostics: [kairoGate.reason]
+    });
+  }
+  if (kairoGate.symlink) {
+    return envelope({
+      state: "error", vaultPath: vaultReal, kairoRoot,
+      error: "Kairo/ is a symlink; refusing",
+      diagnostics: ["Kairo/ is a symlink; refusing"]
+    });
+  }
+
+  const notes = [];
+  const diagnostics = [];
+  await walkKairoNotes(kairoGate.path, kairoGate.path, {
+    notes, diagnostics, depth: 0, maxNotes,
+    lstatFn, readdirFn, realpathFn, existsFn
+  });
+
+  return envelope({
+    state: "available",
+    vaultPath: vaultReal,
+    kairoRoot: kairoGate.path,
+    notes,
+    diagnostics,
+    error: null
+  });
+}
+
+async function walkKairoNotes(dir, kairoRoot, ctx) {
+  if (ctx.notes.length >= ctx.maxNotes || ctx.depth > MAX_WALK_DEPTH) return;
+  let entries;
+  try {
+    entries = await ctx.readdirFn(dir, { withFileTypes: true });
+  } catch {
+    ctx.diagnostics.push("directory unreadable");
+    return;
+  }
+
+  const ordered = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of ordered) {
+    if (ctx.notes.length >= ctx.maxNotes) break;
+    const name = entry.name;
+    if (name === "." || name === ".." || name.includes("\0")) continue;
+    if (isExcludedDirName(name)) continue;
+
+    const full = join(dir, name);
+    const gate = await assertInsideKairoRoot(full, kairoRoot, {
+      lstatFn: ctx.lstatFn, realpathFn: ctx.realpathFn, existsFn: ctx.existsFn
+    });
+    if (!gate.ok) {
+      ctx.diagnostics.push(`skipped unsafe path (${gate.reason})`);
+      continue;
+    }
+    if (gate.missing) continue;
+
+    let st;
+    try { st = await ctx.lstatFn(full); }
+    catch {
+      ctx.diagnostics.push("entry unreadable");
+      continue;
+    }
+
+    if (st.isSymbolicLink()) {
+      ctx.diagnostics.push("skipped symlink");
+      continue;
+    }
+    if (st.isDirectory()) {
+      await walkKairoNotes(gate.path, kairoRoot, { ...ctx, depth: ctx.depth + 1 });
+      continue;
+    }
+    if (!st.isFile()) continue;
+    if (!isAllowedKairoNoteName(name)) continue;
+
+    const rel = gate.path.slice(kairoRoot.length).replace(/^[\\/]/, "").split(sep).join("/");
+    ctx.notes.push({
+      relativePath: rel,
+      title: basename(name, ".md")
+    });
+  }
+}
+
+/** Pure helper for callers composing relative note paths under Kairo/. */
+export function resolveKairoNotePath(kairoRoot, relativePath) {
+  const root = resolve(kairoRoot);
+  const parts = String(relativePath ?? "").split(/[/\\]/).filter(Boolean);
+  if (parts.length === 0 || parts.some((p) => p === ".." || p.includes("\0"))) {
+    return { ok: false, reason: "invalid relativePath" };
+  }
+  if (parts.some((p) => isExcludedDirName(p) || isSecretBasename(p))) {
+    return { ok: false, reason: "relativePath excluded" };
+  }
+  const claimed = resolve(join(root, ...parts));
+  if (!isPathInside(root, claimed)) {
+    return { ok: false, reason: "path escapes Kairo/" };
+  }
+  return { ok: true, path: claimed };
+}