Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
18.4 KB
Raw Blame
/**
 * createNote authoring modes (provenance-at-the-boundary, Unit C):
 * `ifExists: "skip"`, `strict` pre-write validation, and template-mode
 * bodies.
 *
 * Three properties are load-bearing and each has its own test here:
 *
 *   - With none of the three options set, the primitive is
 *     byte-identical to the release before them. The sharp form of that
 *     is a document the strict validator would reject (no frontmatter at
 *     all) still being written when `strict` is unset.
 *   - A skip is DISCRIMINATED from a create. Returning the same shape
 *     for both would be the silent fallback this wave forbids, so the
 *     result carries an `outcome` a caller cannot misread, and a skipped
 *     call leaves the vault tree byte-for-byte unchanged.
 *   - The write-batch surface keeps refusing an existing target. Batches
 *     are all-or-nothing; a per-operation skip would make "applied"
 *     mean two different things in one result list.
 *
 * The pre-existing refusal behaviour is pinned by `create-note.test.ts`,
 * which stays untouched and green.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  rmSync,
  statSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join, relative } from "node:path";

import {
  createNote,
  CreateNoteError,
  type CreateNoteResult,
} from "../../../../src/core/brain/notes/create-note.ts";
import { listNoteWrites } from "../../../../src/core/brain/notes/write-log.ts";
import { applyWriteBatch, WriteBatchError } from "../../../../src/core/brain/write-batch.ts";

/**
 * One raw C0 control character, built rather than typed so it is
 * visible in source and survives a formatter. `validateArtifact`
 * rejects any C0 byte except tab, newline and carriage return.
 */
const CONTROL_CHAR = String.fromCharCode(7);

/** The YAML fence `formatFrontmatter` opens and closes the block with. */
const FRONTMATTER_FENCE = "---";
/** What separates a frontmatter key from its value on one line. */
const FRONTMATTER_KEY_SEPARATOR = ":";

/**
 * One fixed create input, reused so the with-options and without-options
 * cases differ in exactly one thing: whether an option was supplied. It
 * carries three frontmatter keys in a deliberate, non-alphabetical order,
 * because a reordering is one of the two ways the bytes can move without
 * any assertion on `created`/`outcome` noticing.
 */
const BASELINE_INPUT = Object.freeze({
  path: "Notes/Golden.md",
  frontmatter: Object.freeze({ title: "Golden", type: "note", tags: Object.freeze(["a", "b"]) }),
  content: "Body line one.\n\nBody line two.",
});

/**
 * The exact bytes {@link BASELINE_INPUT} produces with none of the three
 * authoring options set. Pinned as a literal rather than recomputed from
 * the implementation, because an expectation derived from the
 * implementation cannot notice the implementation moving: an
 * unconditional spread adding one frontmatter key, or a reordering of the
 * block, changes this string and nothing else in this file.
 *
 * It caught exactly that, once, on purpose. The trailing
 * `origin_channel` line is the server-derived origin channel (Unit C of
 * the nothing-writes-silently wave): `createNote` now stamps the channel
 * of the process that wrote the note, merged LAST so a caller cannot
 * name it. It reads `unset` here because a test harness is not one of
 * the entry points that claims a channel, and `unset` is the explicit
 * literal for that rather than a guess. The three authoring options are
 * still byte-neutral when absent, which is what these tests measure; the
 * stamp is unconditional by design and is part of the golden now.
 */
const GOLDEN_BASELINE_NOTE =
  "---\ntitle: Golden\ntype: note\ntags: [a, b]\norigin_channel: unset\n---\n\n" +
  "Body line one.\n\nBody line two.\n";

/** Frontmatter key order of the note, top to bottom, stamp last. */
const GOLDEN_BASELINE_FRONTMATTER_KEYS: ReadonlyArray<string> = Object.freeze([
  "title",
  "type",
  "tags",
  "origin_channel",
]);

/**
 * The bytes for a note with no frontmatter MAP at all. The block is no
 * longer empty: the origin-channel stamp is the one key every created
 * note carries, whatever the caller supplied.
 */
const GOLDEN_BARE_NOTE = "---\norigin_channel: unset\n---\n\njust a body\n";

/**
 * Result field order the MCP surface and the SDK both read.
 *
 * `write_id` joined it with the note-write record (who-wrote-what,
 * Task A): every created note now names the log event that attributes
 * it, or names why there is none. A skipped result deliberately does NOT
 * grow the field - see {@link GOLDEN_SKIPPED_RESULT_KEYS}.
 */
const GOLDEN_RESULT_KEYS: ReadonlyArray<string> = Object.freeze([
  "path",
  "outcome",
  "created",
  "write_id",
]);

/**
 * A skip authored no bytes, so it has no write to attribute. Pinned
 * separately and WITHOUT `write_id`, because a null id here would read as
 * a lost audit line for a call that never had one.
 */
const GOLDEN_SKIPPED_RESULT_KEYS: ReadonlyArray<string> = Object.freeze([
  "path",
  "outcome",
  "created",
]);

let vault: string;
beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-create-note-modes-"));
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => rmSync(vault, { recursive: true, force: true }));

/** Every path under `root`, with file bytes, so "changed nothing" is checkable. */
function snapshotTree(root: string): ReadonlyArray<string> {
  const out: string[] = [];
  const walk = (dir: string): void => {
    for (const entry of readdirSync(dir).toSorted()) {
      const abs = join(dir, entry);
      const rel = relative(root, abs);
      if (statSync(abs).isDirectory()) {
        out.push(`dir  ${rel}`);
        walk(abs);
      } else {
        out.push(`file ${rel} ${readFileSync(abs, "utf8")}`);
      }
    }
  };
  walk(root);
  return out;
}

/**
 * Frontmatter keys of a written note, in the order they appear on disk.
 * Order is half of what byte-identity means here: the same set of keys
 * emitted in a different sequence is a different file, and a test that
 * compared sets would not see it. A note with no frontmatter block is a
 * caller error rather than an empty list - absence and "could not parse"
 * must not collapse into one answer.
 */
function frontmatterKeys(markdown: string): ReadonlyArray<string> {
  const lines = markdown.split("\n");
  const end = lines[0] === FRONTMATTER_FENCE ? lines.indexOf(FRONTMATTER_FENCE, 1) : -1;
  if (end < 0) {
    throw new Error(`note carries no frontmatter block: ${JSON.stringify(markdown)}`);
  }
  return lines.slice(1, end).map((line) => {
    const colon = line.indexOf(FRONTMATTER_KEY_SEPARATOR);
    if (colon < 0) throw new Error(`frontmatter line carries no key: ${JSON.stringify(line)}`);
    return line.slice(0, colon);
  });
}

/** Read one written note back as raw text, so disk is checked, not memory. */
function writtenNote(path: string): string {
  return readFileSync(join(vault, path), "utf8");
}

describe("createNote - the new options are byte-identical when absent", () => {
  test("with none of the options set the written bytes are the pre-feature golden", () => {
    const res = createNote(vault, { ...BASELINE_INPUT });
    expect(res.outcome).toBe("created");
    // Byte for byte on disk...
    expect(writtenNote(BASELINE_INPUT.path)).toBe(GOLDEN_BASELINE_NOTE);
    // ...frontmatter key order included.
    expect(frontmatterKeys(writtenNote(BASELINE_INPUT.path))).toEqual([
      ...GOLDEN_BASELINE_FRONTMATTER_KEYS,
    ]);
  });

  test("options spread in as undefined write the same bytes as options omitted", () => {
    // That is the shape every conditional spread in this codebase
    // produces when its condition is false, so an option threaded as an
    // explicit `undefined` must not become a different document.
    createNote(vault, {
      ...BASELINE_INPUT,
      ifExists: undefined,
      strict: undefined,
      template: undefined,
      templateVariables: undefined,
    });
    expect(writtenNote(BASELINE_INPUT.path)).toBe(GOLDEN_BASELINE_NOTE);
  });

  test("a document the strict validator would reject is still written when strict is unset", () => {
    // No CALLER frontmatter at all: `validateArtifact` reports
    // frontmatter-missing, which it still can because the origin-channel
    // stamp is merged after validation, not before it.
    const res = createNote(vault, { path: "Notes/Bare.md", content: "just a body" });
    expect(res.created).toBe(true);
    // The whole file, not a substring: an empty frontmatter block is part
    // of the pre-feature shape and a body-only file is not the same note.
    expect(writtenNote("Notes/Bare.md")).toBe(GOLDEN_BARE_NOTE);
  });

  test("with ifExists unset an existing target is still refused with the exists code", () => {
    createNote(vault, { path: "Notes/Once.md", content: "first" });
    try {
      createNote(vault, { path: "Notes/Once.md", content: "second" });
      throw new Error("expected throw");
    } catch (err) {
      expect(err).toBeInstanceOf(CreateNoteError);
      expect((err as CreateNoteError).code).toBe("exists");
    }
    expect(readFileSync(join(vault, "Notes/Once.md"), "utf8")).toContain("first");
  });

  test("a create reports the created outcome alongside the frozen created flag", () => {
    const res = createNote(vault, { path: "Notes/New.md", content: "x" });
    expect(res.outcome).toBe("created");
    expect(res.created).toBe(true);
    // The result envelope is the one addition this unit makes, and it is
    // pinned in full so a fourth field cannot arrive unannounced.
    expect(Object.keys(res)).toEqual([...GOLDEN_RESULT_KEYS]);
    // The id is the one the note-write event carries, not a placeholder.
    // Narrowed on the discriminant rather than cast, because only the
    // created arm has a write to name.
    if (res.outcome !== "created") throw new Error("expected a created result");
    expect(res.write_id).toMatch(/^nw_\d{14}_[0-9a-f]{16}$/);
  });
});

describe('createNote - ifExists: "skip"', () => {
  test("an existing target returns a skipped outcome a caller cannot read as a create", () => {
    createNote(vault, { path: "Notes/Dup.md", content: "original" });
    const res: CreateNoteResult = createNote(vault, {
      path: "Notes/Dup.md",
      content: "replacement",
      ifExists: "skip",
    });
    expect(res.outcome).toBe("skipped");
    expect(res.created).toBe(false);
    expect(res.path).toBe("Notes/Dup.md");
    // No `write_id`: nothing was written, so there is nothing to
    // attribute and no null to mistake for a lost audit line.
    expect(Object.keys(res)).toEqual([...GOLDEN_SKIPPED_RESULT_KEYS]);
    expect(readFileSync(join(vault, "Notes/Dup.md"), "utf8")).toContain("original");
  });

  test("a skip appends no note-write event: the log records writes, not calls", () => {
    createNote(vault, { path: "Notes/Dup.md", content: "original" });
    expect(listNoteWrites(vault).writes).toHaveLength(1);
    createNote(vault, { path: "Notes/Dup.md", content: "replacement", ifExists: "skip" });
    expect(listNoteWrites(vault).writes).toHaveLength(1);
  });

  test("a skip leaves the vault tree byte-for-byte unchanged, directories included", () => {
    createNote(vault, { path: "A/B/C/Deep.md", content: "original" });
    const before = snapshotTree(vault);
    const res = createNote(vault, {
      path: "A/B/C/Deep.md",
      content: "replacement",
      ifExists: "skip",
    });
    expect(res.outcome).toBe("skipped");
    expect(snapshotTree(vault)).toEqual([...before]);
  });

  test("a free target under skip is created normally", () => {
    const res = createNote(vault, { path: "Notes/Fresh.md", content: "x", ifExists: "skip" });
    expect(res.outcome).toBe("created");
    expect(res.created).toBe(true);
    expect(existsSync(join(vault, "Notes/Fresh.md"))).toBe(true);
  });

  test("an explicit refuse behaves exactly like the default", () => {
    createNote(vault, { path: "Notes/R.md", content: "first" });
    expect(() =>
      createNote(vault, { path: "Notes/R.md", content: "second", ifExists: "refuse" }),
    ).toThrow(CreateNoteError);
  });

  test("skip does not relax any other refusal - traversal is still typed", () => {
    expect(() => createNote(vault, { path: "../escape.md", ifExists: "skip" })).toThrow(
      CreateNoteError,
    );
  });
});

describe("createNote - strict pre-write validation", () => {
  test("a valid document passes and is written", () => {
    const res = createNote(vault, {
      path: "Notes/Good.md",
      frontmatter: { title: "Good", type: "note" },
      content: "Body.",
      strict: true,
    });
    expect(res.outcome).toBe("created");
  });

  test("a document with no frontmatter is refused with the validator's coded violation", () => {
    try {
      createNote(vault, { path: "Notes/Bad.md", content: "body only", strict: true });
      throw new Error("expected throw");
    } catch (err) {
      expect(err).toBeInstanceOf(CreateNoteError);
      const e = err as CreateNoteError;
      expect(e.code).toBe("invalid_document");
      expect(e.violations.map((v) => v.code)).toContain("frontmatter-missing");
    }
    expect(existsSync(join(vault, "Notes/Bad.md"))).toBe(false);
  });

  test("a body carrying raw control characters is refused", () => {
    try {
      createNote(vault, {
        path: "Notes/Ctrl.md",
        frontmatter: { title: "C" },
        content: `a${CONTROL_CHAR}b`,
        strict: true,
      });
      throw new Error("expected throw");
    } catch (err) {
      expect((err as CreateNoteError).violations.map((v) => v.code)).toContain(
        "artifact-control-chars",
      );
    }
    expect(existsSync(join(vault, "Notes/Ctrl.md"))).toBe(false);
  });

  test("a declared type outside the vault's page_types vocabulary is refused", () => {
    try {
      createNote(vault, {
        path: "Notes/Typed.md",
        frontmatter: { title: "T", type: "not-a-declared-page-type" },
        content: "body",
        strict: true,
      });
      throw new Error("expected throw");
    } catch (err) {
      expect((err as CreateNoteError).violations.map((v) => v.code)).toContain(
        "schema-type-unknown",
      );
    }
  });

  test("strict validates the rendered template body, not the raw template", () => {
    // The template text itself is clean; only the RENDERED body carries
    // the control character, so a strict refusal proves the validator
    // ran after rendering rather than before it.
    try {
      createNote(vault, {
        path: "Notes/Tpl.md",
        template: "start {{body}} end",
        templateVariables: { body: CONTROL_CHAR },
        strict: true,
        frontmatter: { title: "T" },
      });
      throw new Error("expected throw");
    } catch (err) {
      expect((err as CreateNoteError).violations.map((v) => v.code)).toContain(
        "artifact-control-chars",
      );
    }
    expect(existsSync(join(vault, "Notes/Tpl.md"))).toBe(false);
  });
});

describe("createNote - template mode", () => {
  test("renders typed variables, a presence section and a list iteration into the body", () => {
    const res = createNote(vault, {
      path: "Notes/Rendered.md",
      frontmatter: { title: "R" },
      template: "# {{title}}\n{{#draft}}(draft){{/draft}}\n{{#tags}}- {{.}}\n{{/tags}}{{ typo }}",
      templateVariables: { title: "R", draft: true, tags: ["a", "b"] },
    });
    expect(res.outcome).toBe("created");
    const md = readFileSync(join(vault, "Notes/Rendered.md"), "utf8");
    expect(md).toContain("# R");
    expect(md).toContain("(draft)");
    expect(md).toContain("- a\n- b\n");
    // The unknown placeholder survives so the typo surfaces in the note.
    expect(md).toContain("{{ typo }}");
  });

  test("a template with no variables renders its literal text", () => {
    createNote(vault, { path: "Notes/Lit.md", template: "plain body" });
    expect(readFileSync(join(vault, "Notes/Lit.md"), "utf8")).toContain("plain body");
  });

  test("content and template together are refused rather than one silently winning", () => {
    try {
      createNote(vault, { path: "Notes/Both.md", content: "a", template: "b" });
      throw new Error("expected throw");
    } catch (err) {
      expect(err).toBeInstanceOf(CreateNoteError);
      expect((err as CreateNoteError).code).toBe("invalid_template");
    }
    expect(existsSync(join(vault, "Notes/Both.md"))).toBe(false);
  });

  test("template variables without a template are refused", () => {
    expect(() =>
      createNote(vault, { path: "Notes/Orphan.md", templateVariables: { a: "b" } }),
    ).toThrow(CreateNoteError);
    expect(existsSync(join(vault, "Notes/Orphan.md"))).toBe(false);
  });

  test("a malformed template is refused and writes nothing", () => {
    try {
      createNote(vault, { path: "Notes/Broken.md", template: "{{#a}}x", templateVariables: {} });
      throw new Error("expected throw");
    } catch (err) {
      expect((err as CreateNoteError).code).toBe("invalid_template");
    }
    expect(existsSync(join(vault, "Notes/Broken.md"))).toBe(false);
  });
});

describe("write_batch keeps refusing an existing target", () => {
  test("a create_note operation on an occupied path aborts the whole batch", () => {
    mkdirSync(join(vault, "Notes"), { recursive: true });
    writeFileSync(join(vault, "Notes/Taken.md"), "original", "utf8");
    try {
      applyWriteBatch(vault, [
        { kind: "create_note", path: "Notes/Fresh.md", content: "x" },
        { kind: "create_note", path: "Notes/Taken.md", content: "y" },
      ]);
      throw new Error("expected throw");
    } catch (err) {
      expect(err).toBeInstanceOf(WriteBatchError);
      expect((err as WriteBatchError).code).toBe("exists");
    }
    // All-or-nothing: the first, valid operation did not land either.
    expect(readFileSync(join(vault, "Notes/Taken.md"), "utf8")).toBe("original");
    expect(existsSync(join(vault, "Notes/Fresh.md"))).toBe(false);
  });

  test("the batch create_note operation exposes no skip policy to opt into", () => {
    const withSkip = {
      kind: "create_note",
      path: "Notes/Taken.md",
      content: "y",
      if_exists: "skip",
    };
    mkdirSync(join(vault, "Notes"), { recursive: true });
    writeFileSync(join(vault, "Notes/Taken.md"), "original", "utf8");
    expect(() =>
      applyWriteBatch(vault, [
        withSkip as unknown as Parameters<typeof applyWriteBatch>[1][number],
      ]),
    ).toThrow(WriteBatchError);
    expect(readFileSync(join(vault, "Notes/Taken.md"), "utf8")).toBe("original");
  });
});