@cueloop/integration-obsidian 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@cueloop/integration-obsidian",
+  "version": "0.1.0-alpha.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@cueloop/extension-api": "workspace:*",
+    "@cueloop/schema": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmurakaru/cueloop.git",
+    "directory": "packages/integrations/obsidian"
+  }
+}

package/src/detect.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { detectVaults, obsidianConfigPath } from "./detect";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "cueloop-obsidian-detect-"));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("detectVaults", () => {
+  test("returns registered vault paths that exist on disk", () => {
+    const alive = join(dir, "notes");
+    mkdirSync(alive);
+    const gone = join(dir, "deleted-vault");
+    const configPath = join(dir, "obsidian.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        vaults: {
+          abc123: { path: alive, ts: 1700000000000, open: true },
+          def456: { path: gone, ts: 1700000000001 },
+        },
+      }),
+    );
+    expect(detectVaults(configPath)).toEqual([alive]);
+  });
+
+  test("missing or malformed config yields no vaults", () => {
+    expect(detectVaults(join(dir, "nope.json"))).toEqual([]);
+    const broken = join(dir, "broken.json");
+    writeFileSync(broken, "not json");
+    expect(detectVaults(broken)).toEqual([]);
+    const empty = join(dir, "empty.json");
+    writeFileSync(empty, "{}");
+    expect(detectVaults(empty)).toEqual([]);
+  });
+});
+
+describe("obsidianConfigPath", () => {
+  test("resolves per platform", () => {
+    expect(obsidianConfigPath("darwin")).toContain(join("Library", "Application Support", "obsidian", "obsidian.json"));
+    expect(obsidianConfigPath("linux")).toContain(join("obsidian", "obsidian.json"));
+    expect(obsidianConfigPath("win32")).toContain(join("obsidian", "obsidian.json"));
+  });
+});

package/src/detect.ts

@@ -0,0 +1,35 @@
+/**
+ * Vault auto-detection: Obsidian keeps a registry of known vaults in its own
+ * config file. We read it and return the vault paths that still exist on
+ * disk. The config path is overridable for tests.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Platform-specific location of Obsidian's own obsidian.json. */
+export function obsidianConfigPath(platform: NodeJS.Platform = process.platform): string {
+  if (platform === "darwin") {
+    return join(homedir(), "Library", "Application Support", "obsidian", "obsidian.json");
+  }
+  if (platform === "win32") {
+    return join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "obsidian", "obsidian.json");
+  }
+  return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "obsidian", "obsidian.json");
+}
+
+/** Vault paths registered with Obsidian that exist on disk. */
+export function detectVaults(configPath: string = obsidianConfigPath()): string[] {
+  try {
+    const raw = JSON.parse(readFileSync(configPath, "utf8")) as {
+      vaults?: Record<string, { path?: string }>;
+    };
+    return Object.values(raw.vaults ?? {})
+      .map((v) => v.path)
+      .filter((p): p is string => typeof p === "string" && existsSync(p));
+  } catch {
+    // no Obsidian install, or an unreadable registry: no vaults
+    return [];
+  }
+}

package/src/export.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ReviewSession } from "@cueloop/schema";
+import { Registry } from "@cueloop/extension-api";
+import { OBSIDIAN_DEFAULTS, exportSession, shouldExport, type ObsidianConfig } from "./export";
+import { createObsidianExtension } from "./extension";
+import { frontmatter } from "./frontmatter";
+
+const NOW = new Date("2026-08-07T12:34:56.000Z");
+
+function resolvedSession(overrides: Partial<ReviewSession> = {}): ReviewSession {
+  return {
+    schemaVersion: "1",
+    id: "s_test1",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: {
+      type: "plan",
+      content: "# Migration Plan\n\nMove the store.\n",
+      meta: { title: "Migration Plan" },
+    },
+    revisions: [{ revision: 1, content: "# Migration Plan\n\nMove the store.\n", submittedAt: NOW.toISOString() }],
+    annotations: [],
+    verdict: { kind: "approve", summary: "ship it", feedback: "", resolvedAt: NOW.toISOString() },
+    status: "resolved",
+    createdAt: NOW.toISOString(),
+    ...overrides,
+  };
+}
+
+let vault: string;
+
+beforeEach(() => {
+  vault = mkdtempSync(join(tmpdir(), "cueloop-obsidian-vault-"));
+});
+afterEach(() => {
+  rmSync(vault, { recursive: true, force: true });
+});
+
+function config(overrides: Partial<ObsidianConfig> = {}): ObsidianConfig {
+  return { ...OBSIDIAN_DEFAULTS, vault, ...overrides };
+}
+
+describe("exportSession", () => {
+  test("writes the final plan with frontmatter into vault/folder", () => {
+    const session = resolvedSession();
+    const result = exportSession(session, config(), NOW);
+    expect(result.success).toBe(true);
+    expect(result.path).toBe(join(vault, "cueloop", "2026-08-07 - Migration Plan.md"));
+    const written = readFileSync(result.path!, "utf8");
+    expect(written).toBe(`${frontmatter(session, NOW)}\n\n# Migration Plan\n\nMove the store.\n`);
+    expect(written).toContain("created: 2026-08-07T12:34:56.000Z");
+    expect(written).toContain("source: cueloop");
+    expect(written).toContain("session: s_test1");
+    expect(written).toContain("verdict: approve");
+  });
+
+  test("the working copy wins over the submitted content", () => {
+    const session = resolvedSession({ workingCopy: "# Migration Plan\n\nMove the store carefully.\n" });
+    const result = exportSession(session, config(), NOW);
+    expect(readFileSync(result.path!, "utf8")).toContain("Move the store carefully.");
+  });
+
+  test("never overwrites: collisions get counting suffixes", () => {
+    const session = resolvedSession();
+    const first = exportSession(session, config(), NOW);
+    const second = exportSession(session, config(), NOW);
+    const third = exportSession(session, config(), NOW);
+    expect(second.path).toBe(join(vault, "cueloop", "2026-08-07 - Migration Plan 2.md"));
+    expect(third.path).toBe(join(vault, "cueloop", "2026-08-07 - Migration Plan 3.md"));
+    expect(existsSync(first.path!)).toBe(true);
+  });
+
+  test("no vault configured and none detected fails without writing", () => {
+    const emptyConfigPath = join(vault, "obsidian.json");
+    const result = exportSession(resolvedSession(), config({ vault: undefined, obsidianConfigPath: emptyConfigPath }), NOW);
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("no Obsidian vault");
+  });
+
+  test("a configured vault path that does not exist fails", () => {
+    const result = exportSession(resolvedSession(), config({ vault: join(vault, "missing") }), NOW);
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("vault not found");
+  });
+
+  test("falls back to the first auto-detected vault", () => {
+    const detected = join(vault, "detected-vault");
+    mkdirSync(detected);
+    const obsidianJson = join(vault, "obsidian.json");
+    writeFileSync(obsidianJson, JSON.stringify({ vaults: { v1: { path: detected } } }));
+    const result = exportSession(resolvedSession(), config({ vault: undefined, obsidianConfigPath: obsidianJson }), NOW);
+    expect(result.success).toBe(true);
+    expect(result.path).toBe(join(detected, "cueloop", "2026-08-07 - Migration Plan.md"));
+  });
+});
+
+describe("obsidian extension", () => {
+  test("registers the exporter through the extension API and exports a resolved session", async () => {
+    const registry = new Registry();
+    const record = await registry.load("obsidian", createObsidianExtension(config()));
+    expect(record.errors).toEqual([]);
+    const exporter = record.exporters.get("obsidian");
+    expect(exporter).toBeDefined();
+    const result = await exporter!(resolvedSession());
+    expect(result.success).toBe(true);
+    expect(existsSync(result.path!)).toBe(true);
+  });
+});
+
+describe("shouldExport", () => {
+  test("approve exports only approvals", () => {
+    expect(shouldExport("approve", "approve")).toBe(true);
+    expect(shouldExport("approve", "request_changes")).toBe(false);
+    expect(shouldExport("approve", "comment")).toBe(false);
+  });
+
+  test("resolve exports any verdict", () => {
+    expect(shouldExport("resolve", "approve")).toBe(true);
+    expect(shouldExport("resolve", "request_changes")).toBe(true);
+    expect(shouldExport("resolve", "comment")).toBe(true);
+  });
+
+  test("manual never auto-exports", () => {
+    expect(shouldExport("manual", "approve")).toBe(false);
+    expect(shouldExport("manual", "request_changes")).toBe(false);
+  });
+});

package/src/export.ts

@@ -0,0 +1,59 @@
+/**
+ * Export a session's final plan (working copy when the reviewer edited,
+ * else the submitted content) into an Obsidian vault as a markdown note
+ * with provenance frontmatter. Pure filesystem writes; never overwrites.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ReviewSession, VerdictKind } from "@cueloop/schema";
+import { detectVaults } from "./detect";
+import { formatFilename, titleFrom, uniquePath, type Separator } from "./filename";
+import { frontmatter } from "./frontmatter";
+
+export type ExportOn = "approve" | "resolve" | "manual";
+
+export interface ObsidianConfig {
+  /** Vault path; when unset, the first auto-detected vault is used. */
+  vault?: string;
+  folder: string;
+  filenameFormat: string;
+  separator: Separator;
+  exportOn: ExportOn;
+  /** Override for Obsidian's own config file location (tests). */
+  obsidianConfigPath?: string;
+}
+
+export const OBSIDIAN_DEFAULTS: ObsidianConfig = {
+  folder: "cueloop",
+  filenameFormat: "{YYYY}-{MM}-{DD} - {title}",
+  separator: "space",
+  exportOn: "manual",
+};
+
+/** approve exports only approvals; resolve exports any verdict; manual never auto-exports. */
+export function shouldExport(exportOn: ExportOn, verdict: VerdictKind): boolean {
+  if (exportOn === "approve") return verdict === "approve";
+  return exportOn === "resolve";
+}
+
+export interface ExportResult {
+  success: boolean;
+  path?: string;
+  error?: string;
+}
+
+export function exportSession(session: ReviewSession, config: ObsidianConfig, now: Date = new Date()): ExportResult {
+  const vault = config.vault ?? detectVaults(config.obsidianConfigPath)[0];
+  if (!vault) return { success: false, error: "no Obsidian vault configured or detected" };
+  if (!existsSync(vault)) return { success: false, error: `vault not found: ${vault}` };
+
+  const content = session.workingCopy ?? session.artifact.content;
+  const title = titleFrom(content, session.artifact.meta.title);
+  const dir = join(vault, config.folder);
+  mkdirSync(dir, { recursive: true });
+  const base = formatFilename(config.filenameFormat, title, now, config.separator);
+  const path = uniquePath(dir, base);
+  writeFileSync(path, `${frontmatter(session, now)}\n\n${content}`);
+  return { success: true, path };
+}

package/src/extension.ts

@@ -0,0 +1,14 @@
+/**
+ * The bundled Obsidian extension: a plain factory over the pure core,
+ * registering through the public extension API like any third-party
+ * extension would (no privileged built-ins).
+ */
+
+import type { ExtensionFactory } from "@cueloop/extension-api";
+import { exportSession, type ObsidianConfig } from "./export";
+
+export function createObsidianExtension(config: ObsidianConfig): ExtensionFactory {
+  return (cueloop) => {
+    cueloop.registerExporter("obsidian", async (session) => exportSession(session, config));
+  };
+}

package/src/filename.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { formatFilename, sanitizeTitle, titleFrom, uniquePath } from "./filename";
+
+const DATE = new Date("2026-08-07T12:00:00Z");
+
+describe("titleFrom", () => {
+  test("uses the first H1", () => {
+    expect(titleFrom("intro\n\n# Migration Plan\n\n## Steps\n")).toBe("Migration Plan");
+  });
+
+  test("falls back to the provided title, then to untitled", () => {
+    expect(titleFrom("no headings here", "Session Title")).toBe("Session Title");
+    expect(titleFrom("no headings here")).toBe("untitled");
+  });
+
+  test("strips forbidden characters and collapses whitespace", () => {
+    expect(titleFrom('# Fix <the> "store": a/b\\c | d?* (v2) {x} [y] #tag ~ `code`')).toBe(
+      "Fix the store abc d v2 x y tag code",
+    );
+  });
+
+  test("caps the title at 50 characters", () => {
+    const long = "# " + "word ".repeat(20);
+    expect(titleFrom(long).length).toBeLessThanOrEqual(50);
+    expect(titleFrom(long).endsWith(" ")).toBe(false);
+  });
+
+  test("a title of only forbidden characters becomes untitled", () => {
+    expect(sanitizeTitle("###")).toBe("untitled");
+  });
+});
+
+describe("formatFilename", () => {
+  test("renders date tokens and the title with the space separator", () => {
+    expect(formatFilename("{YYYY}-{MM}-{DD} - {title}", "My Plan", DATE, "space")).toBe("2026-08-07 - My Plan");
+  });
+
+  test("dash and underscore separators replace whitespace runs", () => {
+    expect(formatFilename("{YYYY}-{MM}-{DD} - {title}", "My Plan", DATE, "dash")).toBe("2026-08-07---My-Plan");
+    expect(formatFilename("{title}", "My Plan", DATE, "underscore")).toBe("My_Plan");
+  });
+});
+
+describe("uniquePath", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "cueloop-obsidian-name-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("appends counting suffixes instead of overwriting", () => {
+    expect(uniquePath(dir, "plan")).toBe(join(dir, "plan.md"));
+    writeFileSync(join(dir, "plan.md"), "");
+    expect(uniquePath(dir, "plan")).toBe(join(dir, "plan 2.md"));
+    writeFileSync(join(dir, "plan 2.md"), "");
+    expect(uniquePath(dir, "plan")).toBe(join(dir, "plan 3.md"));
+  });
+});

package/src/filename.ts

@@ -0,0 +1,51 @@
+/**
+ * Note naming: title from the plan's first H1, sanitized for filesystems,
+ * formatted through the configured pattern, never overwriting an existing
+ * note (collision suffixes " 2", " 3", ...).
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export type Separator = "space" | "dash" | "underscore";
+
+const SEPARATOR_CHAR: Record<Separator, string> = { space: " ", dash: "-", underscore: "_" };
+
+/** Characters that break filenames or Obsidian links. */
+const FORBIDDEN = /[<>:"/\\|?*(){}[\]#~`]/g;
+
+/** Sanitize a raw title for use as a filesystem name; never empty. */
+export function sanitizeTitle(raw: string): string {
+  const clean = raw.replace(FORBIDDEN, "").replace(/\s+/g, " ").trim();
+  const capped = clean.slice(0, 50).trim();
+  return capped || "untitled";
+}
+
+/** Title = first H1 of the content, else the fallback, sanitized. */
+export function titleFrom(content: string, fallback?: string): string {
+  const h1 = content.match(/^#[ \t]+(.+)$/m)?.[1];
+  return sanitizeTitle(h1 ?? fallback ?? "untitled");
+}
+
+/**
+ * Render the filename pattern ({YYYY}, {MM}, {DD}, {title}); each whitespace
+ * run in the result becomes the configured separator.
+ */
+export function formatFilename(format: string, title: string, date: Date, separator: Separator = "space"): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const name = format
+    .replaceAll("{YYYY}", String(date.getFullYear()))
+    .replaceAll("{MM}", pad(date.getMonth() + 1))
+    .replaceAll("{DD}", pad(date.getDate()))
+    .replaceAll("{title}", title);
+  return name.replace(/\s+/g, SEPARATOR_CHAR[separator]);
+}
+
+/** First free path for base.md in dir: base.md, base 2.md, base 3.md, ... */
+export function uniquePath(dir: string, base: string): string {
+  let candidate = join(dir, `${base}.md`);
+  for (let n = 2; existsSync(candidate); n++) {
+    candidate = join(dir, `${base} ${n}.md`);
+  }
+  return candidate;
+}

package/src/frontmatter.ts

@@ -0,0 +1,14 @@
+/** Frontmatter for exported notes: provenance the vault can query. */
+
+import type { ReviewSession } from "@cueloop/schema";
+
+export function frontmatter(session: ReviewSession, created: Date): string {
+  return [
+    "---",
+    `created: ${created.toISOString()}`,
+    "source: cueloop",
+    `session: ${session.id}`,
+    `verdict: ${session.verdict?.kind ?? "pending"}`,
+    "---",
+  ].join("\n");
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./detect";
+export * from "./filename";
+export * from "./frontmatter";
+export * from "./export";
+export * from "./extension";