@kal-elsam/kairo-runtime 0.12.0 → 0.13.1

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
+    });
+  }
+}