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
/**
* Folder-level note lifecycle: `move-folder` and `rename-folder`
* (t_9571a47f).
*
* The note-file surface is defined per FILE; reorganizing a vault by
* folder means moving notes one at a time by hand, which breaks inbound
* path-spelled wikilinks. A folder move never changes a basename, so the
* bare `[[Name]]` spellings keep resolving and only PATH-spelled links
* break - which one `retargetWikilinks` pass over the successfully moved
* set fixes completely. There is no second (bare-name repair) pass here,
* and the tests pin that the single pass is genuinely complete.
*
* The operation is explicitly NOT atomic and the tests hold it to that
* honesty: occupancy is eliminated by a pre-flight that refuses before
* the first byte moves, and a mid-set I/O failure is NAMED in
* `moveFailures` with the rewrite pairs computed from the successfully
* moved set only - never rolled back, matching the settled partial-
* failure doctrine of the file surface.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
chmodSync,
existsSync,
lstatSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
rmSync,
statSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
import {
BASENAME_REWRITE,
isNoteLifecycleAction,
NOTE_ARCHIVE_ROOT,
NOTE_LIFECYCLE_ACTION,
NOTE_LIFECYCLE_ACTIONS,
noteLifecycle,
NoteLifecycleError,
} from "../../../../src/core/brain/notes/lifecycle.ts";
import {
folderLifecycle,
isFolderLifecycleAction,
} from "../../../../src/core/brain/notes/folder-lifecycle.ts";
import { CHMOD_CANNOT_DENY } from "../../../helpers/platform.ts";
import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
let vault: string;
let configHome: string;
let configPath: string;
/**
* Whether the filesystem hosting the test tmpdir folds case in names:
* probed once, at load, because `test.skipIf` decides at declaration -
* before any per-test vault exists - and the folding behavior belongs to
* the volume, not to the process.
*/
const FOLDS_CASE = (() => {
const probe = mkdtempSync(join(tmpdir(), "o2b-case-probe-"));
try {
mkdirSync(join(probe, "Fold"));
const plain = statSync(join(probe, "Fold"));
const folded = statSync(join(probe, "fold"));
return plain.dev === folded.dev && plain.ino === folded.ino;
} catch {
return false;
} finally {
rmSync(probe, { recursive: true, force: true });
}
})();
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-folder-lifecycle-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-folder-lifecycle-cfg-"));
configPath = join(configHome, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\n`);
bootstrapBrain(vault, { configPath });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
/** Write a note verbatim, creating its parents. */
function note(rel: string, body: string): void {
const abs = join(vault, rel);
mkdirSync(join(abs, ".."), { recursive: true });
writeFileSync(abs, body);
}
function read(rel: string): string {
return readFileSync(join(vault, rel), "utf8");
}
function isDir(rel: string): boolean {
try {
return statSync(join(vault, rel)).isDirectory();
} catch {
return false;
}
}
describe("the folder action vocabulary", () => {
test("move-folder and rename-folder are members of the one lifecycle vocabulary", () => {
expect(NOTE_LIFECYCLE_ACTION.moveFolder).toBe("move-folder");
expect(NOTE_LIFECYCLE_ACTION.renameFolder).toBe("rename-folder");
expect(NOTE_LIFECYCLE_ACTIONS).toContain("move-folder");
expect(NOTE_LIFECYCLE_ACTIONS).toContain("rename-folder");
// The guard reads the same constant, so the CLI check, MCP enum and
// manifest stay in sync from one place.
expect(isNoteLifecycleAction("move-folder")).toBe(true);
expect(isNoteLifecycleAction("rename-folder")).toBe(true);
expect(isNoteLifecycleAction("Move-Folder")).toBe(false);
});
test("the folder guard accepts exactly the two folder actions", () => {
expect(isFolderLifecycleAction("move-folder")).toBe(true);
expect(isFolderLifecycleAction("rename-folder")).toBe(true);
for (const outsider of ["delete", "archive", "rename", "move", null, 42, {}, ""]) {
expect(isFolderLifecycleAction(outsider)).toBe(false);
}
});
});
describe("the folder envelope", () => {
test("a missing source is a typed source_missing refusal", async () => {
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Nope",
to: "Archive-elsewhere",
apply: true,
}),
).rejects.toThrow(NoteLifecycleError);
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/NotAFolder",
to: "Elsewhere",
apply: true,
}),
).rejects.toThrow(/source_missing|no note folder/);
});
test("the vault root is refused as a source", async () => {
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.renameFolder,
path: "",
to: "Everything",
apply: true,
}),
).rejects.toThrow();
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.renameFolder,
path: ".",
to: "Everything",
apply: true,
}),
).rejects.toThrow();
});
test("the Brain machinery root is refused for source and destination alike", async () => {
note("Projects/Old/a.md", "x\n");
// Source under Brain/.
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Brain/reports",
to: "Projects",
apply: true,
}),
).rejects.toThrow(/Brain/);
// Destination under Brain/.
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Brain",
apply: true,
}),
).rejects.toThrow(/Brain/);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
});
test("a vault-scope excluded path is refused, naming the entry", async () => {
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: ".obsidian/plugins",
to: "Projects",
apply: true,
}),
).rejects.toThrow(/excluded by vault\.ignore_paths \(\.obsidian\)/);
});
test("traversal is refused for source and destination", async () => {
note("Projects/Old.md", "x\n");
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/../..",
to: "Elsewhere",
apply: true,
}),
).rejects.toThrow();
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "../outside",
apply: true,
}),
).rejects.toThrow();
expect(existsSync(join(vault, "Projects/Old.md"))).toBe(true);
});
});
describe("the caller's reach over the folder", () => {
test("a move set the caller may not read refuses exactly as a missing folder", async () => {
note("Projects/Old/a.md", "alpha\n");
for (const apply of [false, true]) {
let caught: unknown;
try {
await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply,
readable: () => false,
});
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(NoteLifecycleError);
expect((caught as NoteLifecycleError).code).toBe("source_missing");
}
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Archive"))).toBe(false);
});
test("a folder holding one note the caller may not read refuses without naming it", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Projects/Old/quiet.md", "reserved\n");
for (const apply of [false, true]) {
let caught: unknown;
try {
await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply,
readable: (rel) => !rel.endsWith("quiet.md"),
});
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(NoteLifecycleError);
const refusal = caught as NoteLifecycleError;
expect(refusal.code).toBe("source_missing");
// The refusal reads exactly as a missing folder's: the denied
// note's path names nothing the caller could otherwise learn.
expect(refusal.message).not.toContain("quiet");
}
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/quiet.md"))).toBe(true);
expect(existsSync(join(vault, "Archive"))).toBe(false);
});
test("a denied folder answers a destination mistake as a missing folder, never the destination's error", async () => {
// The reach check runs BEFORE the destination is resolved: a folder
// holding a note the caller may not read answers every later error
// path as a missing folder too. A destination refusal would let a
// deliberately bad `to` tell an existing-but-denied folder apart
// from a missing one - an existence oracle.
note("Projects/Old/quiet.md", "reserved\n");
for (const apply of [false, true]) {
let caught: unknown;
try {
await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Projects/Old/nested",
apply,
readable: () => false,
});
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(NoteLifecycleError);
expect((caught as NoteLifecycleError).code).toBe("source_missing");
}
expect(existsSync(join(vault, "Projects/Old/quiet.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/nested"))).toBe(false);
});
});
describe("move-folder", () => {
test("moves every file and rewrites path-spelled inbound links to the minimal spelling", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Projects/Old/b.md", "beta\n");
note("Notes/Ref.md", "pathed [[Projects/Old/a]] and suffixed [[Projects/Old/a.md]]\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.applied).toBe(true);
expect(res.from).toBe("Projects/Old");
expect(res.to).toBe("Archive/Old");
expect(res.moved.map((m) => m.to).toSorted()).toEqual(["Archive/Old/a.md", "Archive/Old/b.md"]);
expect(res.moveFailures).toEqual([]);
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Archive/Old/b.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(false);
// The minimal spelling of the moved note: the basename is unique, so
// both path-spelled forms collapse onto it.
expect(read("Notes/Ref.md")).toBe("pathed [[a]] and suffixed [[a]]\n");
expect(res.references.filesRewritten).toBe(1);
expect(res.references.basename).toBe(BASENAME_REWRITE.notNeeded);
});
test("leaves bare-basename links untouched and resolving", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Notes/Ref.md", "bare [[a]] and pathed [[Projects/Old/a]]\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
// A folder move never changes a basename, so the bare spelling never
// breaks; rewriting it is not this operation's business.
expect(read("Notes/Ref.md")).toBe("bare [[a]] and pathed [[a]]\n");
expect(res.references.rewrittenSpellings).toEqual([
{ from: "Projects/Old/a.md", to: "a" },
{ from: "Projects/Old/a", to: "a" },
]);
});
test("rewrites to the suffix-less path when the destination basename is contested", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Archive/Other/a.md", "another note that already owns the basename\n");
note("Notes/Ref.md", "pathed [[Projects/Old/a]]\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
// Bare `a` has two carriers after the move, so the minimal honest
// spelling is the suffix-less path.
expect(read("Notes/Ref.md")).toBe("pathed [[Archive/Old/a]]\n");
expect(res.references.rewrittenSpellings).toEqual([
{ from: "Projects/Old/a.md", to: "Archive/Old/a" },
{ from: "Projects/Old/a", to: "Archive/Old/a" },
]);
});
test("rewrites sibling path-spelled links inside the moved folder itself", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Projects/Old/b.md", "see [[Projects/Old/a]]\n");
await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(read("Archive/Old/b.md")).toBe("see [[a]]\n");
});
test("rewrites Brain artifact references and never rewrites the append-only log", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Brain/reports/weekly.md", "- ref [[Projects/Old/a]]\n");
note("Brain/log/2026-10-26.md", "- saw [[Projects/Old/a]]\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(read("Brain/reports/weekly.md")).toBe("- ref [[a]]\n");
// Testimony is read and reported, never rewritten.
expect(read("Brain/log/2026-10-26.md")).toBe("- saw [[Projects/Old/a]]\n");
expect(res.references.inboundFiles).toContain("Brain/log/2026-10-26.md");
});
test("refuses a destination sharing the source's parent - that is rename-folder", async () => {
note("Projects/Old/a.md", "x\n");
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Projects/Elsewhere",
apply: true,
}),
).rejects.toThrow(/wrong_action|use rename-folder/);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
});
test("a destination directory in another parent's subtree moves without complaint", async () => {
note("Projects/Old/a.md", "alpha\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive/2026",
apply: true,
});
// `Archive/2026` sits in `Archive`, not in `Projects`, so the folder's
// parent genuinely changes and the move is exactly what was asked for.
expect(res.to).toBe("Archive/2026/Old");
expect(existsSync(join(vault, "Archive/2026/Old/a.md"))).toBe(true);
});
test("moving to the vault root lands the folder at the top level", async () => {
note("Projects/Old/a.md", "alpha\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "",
apply: true,
});
// The root is a legitimate DESTINATION directory (a folder may land
// at the top level) while staying refused as a SUBJECT.
expect(res.to).toBe("Old");
expect(existsSync(join(vault, "Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old"))).toBe(false);
});
test("a destination inside the source subtree is refused - the folder would nest inside itself", async () => {
note("Projects/Old/a.md", "alpha\n");
mkdirSync(join(vault, "Projects/Sub"), { recursive: true });
let caught: unknown;
try {
await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects",
to: "Projects/Sub",
apply: true,
});
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(NoteLifecycleError);
const refusal = caught as NoteLifecycleError;
expect(refusal.code).toBe("destination_inside_source");
// The refusal names both paths, so the caller can see the collision.
expect(refusal.message).toContain("Projects/Sub");
expect(refusal.message).toContain("Projects");
// Deeper nesting is the same refusal.
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects",
to: "Projects/Sub/Deeper",
apply: true,
}),
).rejects.toThrow(NoteLifecycleError);
// Nothing moved: the tree is exactly where it was.
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Sub/Projects"))).toBe(false);
});
test("a destination that collapses onto the source folder is refused as unchanged", async () => {
note("Projects/Old/a.md", "x\n");
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Projects",
apply: true,
}),
).rejects.toThrow(/destination is the source folder/);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
});
test("a FILE occupying the destination folder path refuses with nothing moved", async () => {
note("Projects/Old/a.md", "source\n");
note("Archive/Old", "occupied by a stranger\n");
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
}),
).rejects.toThrow(/nothing was moved/);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
expect(read("Archive/Old")).toBe("occupied by a stranger\n");
});
test("an occupied destination DIRECTORY refuses with nothing moved", async () => {
note("Projects/Old/a.md", "source\n");
note("Archive/Old/stranger.md", "occupied\n");
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
}),
).rejects.toThrow(/nothing was moved/);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
expect(read("Archive/Old/stranger.md")).toBe("occupied\n");
});
test("an empty destination directory is not an occupancy: the files land in it", async () => {
note("Projects/Old/a.md", "source\n");
mkdirSync(join(vault, "Archive/Old"), { recursive: true });
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old"))).toBe(false);
});
test("an empty folder moves with an empty moved set and no residue", async () => {
mkdirSync(join(vault, "Projects/Empty"), { recursive: true });
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Empty",
to: "Archive",
apply: true,
});
expect(res.moved).toEqual([]);
expect(res.moveFailures).toEqual([]);
expect(existsSync(join(vault, "Projects/Empty"))).toBe(false);
expect(isDir("Archive/Empty")).toBe(true);
});
test("a spelling that matches nothing in the walk refuses instead of succeeding as a no-op", async () => {
// The vault's real folder, as the walk spells it.
note("Projects/Old/a.md", "alpha\n");
// A second, differently-cased directory this host tells apart: the
// caller's spelling stats as a real, non-empty folder while matching
// none of the walked paths - the shape a case or normalization
// mismatch takes on a case-insensitive host.
mkdirSync(join(vault, "projects/old"), { recursive: true });
writeFileSync(join(vault, "projects/old/img.png"), "png\n");
let caught: unknown;
try {
await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "projects/old",
to: "Archive",
apply: true,
});
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(NoteLifecycleError);
const refusal = caught as NoteLifecycleError;
expect(refusal.code).toBe("move_set_empty");
expect(refusal.message).toContain("projects/old");
expect(refusal.message).toMatch(/case|normaliz/i);
// Nothing was touched: the real folder stands and no destination
// skeleton appeared.
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Archive/old"))).toBe(false);
// A plan-only run of the same spelling is the same refusal: a plan
// of nothing over a non-empty folder is a preview of a lie.
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "projects/old",
to: "Archive",
}),
).rejects.toThrow(/move_set_empty|not empty on disk/);
});
test("non-Markdown residue in the source folder is named, not silently clean", async () => {
note("Projects/Old/a.md", "alpha\n");
writeFileSync(join(vault, "Projects/Old/img.png"), "png\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.applied).toBe(true);
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
// The note relocated; the image is not a note and did not move - and
// the result names what stayed in the source folder after the prune.
expect(res.leftBehind).toEqual(["img.png"]);
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/img.png"))).toBe(true);
// A move that genuinely empties its source folder names nothing.
note("Other/Sub/b.md", "beta\n");
const clean = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Other/Sub",
to: "Archive",
apply: true,
});
expect(clean.leftBehind).toEqual([]);
expect(existsSync(join(vault, "Other/Sub"))).toBe(false);
});
test("dry run is the default: it reports the full plan and writes nothing", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Notes/Ref.md", "[[Projects/Old/a]]\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
});
expect(res.applied).toBe(false);
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
expect(res.references.inboundFiles).toEqual(["Notes/Ref.md"]);
expect(res.references.filesRewritten).toBe(0);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Archive/Old"))).toBe(false);
expect(read("Notes/Ref.md")).toBe("[[Projects/Old/a]]\n");
});
test.skipIf(CHMOD_CANNOT_DENY)(
"a mid-set move failure is named, not rolled back, and the rewrite uses the moved set only",
async () => {
note("Projects/Old/a.md", "alpha\n");
note("Projects/Old/sub/b.md", "beta\n");
note("Notes/A.md", "moves [[Projects/Old/a]]\n");
note("Notes/B.md", "moves [[Projects/Old/sub/b]]\n");
// The nested directory becomes unmovable AFTER the plan and after
// `a.md` has already relocated: the EACCES lands mid-set.
chmodSync(join(vault, "Projects/Old/sub"), 0o500);
let res;
try {
res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
} finally {
chmodSync(join(vault, "Projects/Old/sub"), 0o700);
}
expect(res.applied).toBe(true);
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
expect(res.moveFailures).toHaveLength(1);
expect(res.moveFailures[0]!.path).toBe("Projects/Old/sub/b.md");
// The prune could not empty the source, and the residue names what
// is still sitting in it.
expect(res.leftBehind).toEqual(["sub"]);
// The residue is exactly where the report says: `a.md` is at its
// new path, `b.md` stays at its old one.
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/sub/b.md"))).toBe(true);
// Pairs were computed from the moved set ONLY: the link to the
// moved note is rewritten, the link to the failed note still
// resolves to where the bytes actually are.
expect(read("Notes/A.md")).toBe("moves [[a]]\n");
expect(read("Notes/B.md")).toBe("moves [[Projects/Old/sub/b]]\n");
// The failed move leaves exactly one name for the file: the fault
// struck after the destination name was linked, and that second
// name was dropped - the report's "never moved" stays true.
expect(existsSync(join(vault, "Archive/Old/sub/b.md"))).toBe(false);
},
);
test.skipIf(CHMOD_CANNOT_DENY)(
"a set where nothing moves leaves no invented destination folder behind",
async () => {
note("Projects/Old/a.md", "alpha\n");
// Every relocation fails the same way: the destination name lands,
// then dropping the source name is refused, so the set finishes
// with nothing moved - and the destination folder the apply
// created for the set must not stay behind as residue the report
// contradicts.
chmodSync(join(vault, "Projects/Old"), 0o500);
let res;
try {
res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
} finally {
chmodSync(join(vault, "Projects/Old"), 0o700);
}
expect(res.applied).toBe(true);
expect(res.moved).toEqual([]);
expect(res.moveFailures).toHaveLength(1);
// Nothing was invented at the destination, and the source stands
// exactly where the report says its bytes are.
expect(existsSync(join(vault, "Archive"))).toBe(false);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
},
);
test.skipIf(CHMOD_CANNOT_DENY)(
"a fully-failed set cleans its invented subtree and spares a pre-existing destination parent",
async () => {
// Nested source: the per-file machinery creates Archive/Old/sub for
// the failed move, and the cleanup takes the whole invented branch,
// not just the destination folder itself. An EMPTY Archive that was
// already here stays - a directory that existed before is not this
// operation's to remove, and the move lands under it.
note("Projects/Old/sub/a.md", "alpha\n");
mkdirSync(join(vault, "Archive"), { recursive: true });
chmodSync(join(vault, "Projects/Old/sub"), 0o500);
let res;
try {
res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
} finally {
chmodSync(join(vault, "Projects/Old/sub"), 0o700);
}
expect(res.applied).toBe(true);
expect(res.moved).toEqual([]);
expect(res.moveFailures).toHaveLength(1);
// The invented branch is gone down to the destination folder; the
// pre-existing parent stands, and the source is exactly where the
// report says its bytes are.
expect(existsSync(join(vault, "Archive/Old"))).toBe(false);
expect(isDir("Archive")).toBe(true);
expect(existsSync(join(vault, "Projects/Old/sub/a.md"))).toBe(true);
},
);
test.skipIf(CHMOD_CANNOT_DENY)(
"a partially-failed set still cleans the empty branch a failed move invented",
async () => {
// One note relocates; the nested one fails the source-name drop
// after its branch was created for it. The set ends half-moved, and
// the empty branch the failed move invented must not stand beside a
// report that says it never moved - while the moved note's own
// branch, holding real bytes, does.
note("Projects/Old/a.md", "alpha\n");
note("Projects/Old/sub/b.md", "beta\n");
chmodSync(join(vault, "Projects/Old/sub"), 0o500);
let res;
try {
res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
} finally {
chmodSync(join(vault, "Projects/Old/sub"), 0o700);
}
expect(res.applied).toBe(true);
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
expect(res.moveFailures).toHaveLength(1);
expect(res.moveFailures[0]!.path).toBe("Projects/Old/sub/b.md");
// The moved note stands; the failed move's invented branch is gone.
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Archive/Old/sub"))).toBe(false);
// The source keeps the failed file exactly where the report says.
expect(existsSync(join(vault, "Projects/Old/sub/b.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old"))).toBe(true);
},
);
test("a foreign file at a cleared destination name survives the move's fault", async () => {
note("Projects/Old/a.md", "alpha\n");
// The pre-flight cleared the destination name; a foreign file appears
// there before the link - the race the occupied-name guard exists
// for, produced through the relocation seam. The refusal is the move's
// own, and the cleanup must not unlink bytes it did not write.
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
relocate: (_fromAbs, toAbs, label) => {
writeFileSync(toAbs, "foreign bytes\n");
throw new NoteLifecycleError(
"destination_occupied",
`destination already exists: ${label}`,
);
},
});
expect(res.applied).toBe(true);
expect(res.moved).toEqual([]);
expect(res.moveFailures).toHaveLength(1);
expect(res.moveFailures[0]!.path).toBe("Projects/Old/a.md");
expect(res.moveFailures[0]!.reason).toContain("destination already exists");
// The foreign file stands, and the invented branch around it stands
// with it; the source still holds the note.
expect(readFileSync(join(vault, "Archive/Old/a.md"), "utf8")).toBe("foreign bytes\n");
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
});
test("a top-level folder moves under a sibling top-level directory", async () => {
note("Old/a.md", "alpha\n");
mkdirSync(join(vault, "Archive"), { recursive: true });
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Old",
to: "Archive",
apply: true,
});
expect(res.from).toBe("Old");
expect(res.to).toBe("Archive/Old");
expect(res.moved).toEqual([{ from: "Old/a.md", to: "Archive/Old/a.md" }]);
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Old"))).toBe(false);
});
test("a clean nested move leaves no empty skeleton and names no residue", async () => {
note("Projects/Old/sub/deep/b.md", "beta\n");
note("Projects/Old/a.md", "alpha\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.moveFailures).toEqual([]);
expect(res.leftBehind).toEqual([]);
expect(existsSync(join(vault, "Projects/Old"))).toBe(false);
expect(existsSync(join(vault, "Projects/Old/sub"))).toBe(false);
expect(existsSync(join(vault, "Archive/Old/sub/deep/b.md"))).toBe(true);
});
test("directories the move never touched keep standing after a partial prune", async () => {
// One note moves; a no-Markdown subtree and a pre-existing empty
// sibling stay. The prune's candidates are the MOVED files' ancestor
// chains, so the removal cannot walk the source's subtree and delete
// directories this operation never touched - and the source folder
// itself stands because the untouched residue still fills it.
note("Projects/Old/a.md", "alpha\n");
mkdirSync(join(vault, "Projects/Old/sub"), { recursive: true });
writeFileSync(join(vault, "Projects/Old/sub/img.png"), "png\n");
mkdirSync(join(vault, "Projects/Old/empty"), { recursive: true });
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
expect(res.leftBehind).toEqual(["empty", "sub"]);
expect(existsSync(join(vault, "Projects/Old"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/sub/img.png"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/empty"))).toBe(true);
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
});
test("the prune never follows a symlinked directory out of the source", async () => {
// The candidates are derived from moved files' vault-relative
// spellings, never from a filesystem walk of the source: a linked
// directory under the source is neither descended into nor offered
// to the removal, so nothing outside the source - here a real empty
// directory the link resolves to - is this operation's to delete.
note("Projects/Old/a.md", "alpha\n");
mkdirSync(join(vault, "Outside/inner"), { recursive: true });
symlinkSync(join(vault, "Outside"), join(vault, "Projects/Old/link"), "dir");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
expect(existsSync(join(vault, "Outside/inner"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/link"))).toBe(true);
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
});
test.skipIf(!FOLDS_CASE)(
"a case-only folder rename is refused rather than half-reported",
async () => {
note("Projects/Old/a.md", "alpha\n");
// The refusal exists for the host that folds case: there the two
// spellings name one directory entry, which moving files cannot
// re-case. A host that tells them apart reaches an ordinary rename
// instead, so the test is SKIPPED there - reported as a skip, never
// a silent early pass.
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.renameFolder,
path: "Projects/Old",
to: "old",
apply: true,
}),
).rejects.toThrow(/destination_unchanged|case-only/);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
},
);
test("a folder holding only attachments moves an empty set and keeps its contents", async () => {
mkdirSync(join(vault, "Assets/img"), { recursive: true });
writeFileSync(join(vault, "Assets/img/logo.png"), "png\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Assets/img",
to: "Archive",
apply: true,
});
expect(res.moved).toEqual([]);
expect(res.moveFailures).toEqual([]);
expect(res.leftBehind).toEqual(["logo.png"]);
expect(existsSync(join(vault, "Assets/img/logo.png"))).toBe(true);
expect(existsSync(join(vault, "Archive/img/logo.png"))).toBe(false);
// A folder that keeps its entries creates nothing at the destination:
// an empty directory the move invented is residue in the vault.
expect(existsSync(join(vault, "Archive/img"))).toBe(false);
});
test("a dry run reports the spellings the apply would write", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Notes/Ref.md", "pathed [[Projects/Old/a]]\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Elsewhere",
});
expect(res.applied).toBe(false);
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Elsewhere/Old/a.md" }]);
expect(res.references.rewrittenSpellings).toEqual([
{ from: "Projects/Old/a.md", to: "a" },
{ from: "Projects/Old/a", to: "a" },
]);
});
});
describe("rename-folder", () => {
test("renames in place and rewrites path-spelled links", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Notes/Ref.md", "pathed [[Projects/Old/a]]\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.renameFolder,
path: "Projects/Old",
to: "New",
apply: true,
});
expect(res.from).toBe("Projects/Old");
expect(res.to).toBe("Projects/New");
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Projects/New/a.md" }]);
expect(existsSync(join(vault, "Projects/New/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old"))).toBe(false);
expect(read("Notes/Ref.md")).toBe("pathed [[a]]\n");
});
test("a cross-parent destination is refused - that is move-folder", async () => {
note("Projects/Old/a.md", "x\n");
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.renameFolder,
path: "Projects/Old",
to: "Elsewhere/Old",
apply: true,
}),
).rejects.toThrow(/wrong_action|use move-folder/);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
});
test("a multi-segment name is a cross-parent move and is refused by name", async () => {
note("Projects/Old/a.md", "x\n");
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.renameFolder,
path: "Projects/Old",
to: "Sub/New",
apply: true,
}),
).rejects.toThrow(/wrong_action|use move-folder/);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
});
test("delete and archive are note-file actions and refuse a folder subject", async () => {
mkdirSync(join(vault, "Projects/Old"), { recursive: true });
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: "Projects/Old",
apply: true,
}),
).rejects.toThrow(NoteLifecycleError);
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.archive,
path: "Projects/Old",
apply: true,
}),
).rejects.toThrow(NoteLifecycleError);
expect(isDir("Projects/Old")).toBe(true);
});
test("the archive root is an ordinary destination for move-folder - no archive semantics here", async () => {
note("Projects/Old/a.md", "x\n");
// The folder surface has no archive action; a caller-chosen
// destination that happens to be named like one is just a move, with
// no confirm ladder beyond the surface's own.
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: NOTE_ARCHIVE_ROOT,
apply: true,
}),
).resolves.toBeDefined();
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
});
});
describe("the count guard over the folder move set", () => {
test("--expect counts the files the apply will write, not the files moved", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Projects/Old/b.md", "beta\n");
note("Notes/Ref.md", "[[Projects/Old/a]] and [[Projects/Old/b]]\n");
// Two notes move; ONE file holds the inbound references the apply
// will write. The plan names that file and `--expect` counts it.
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
expect: 7,
}),
).rejects.toThrow();
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
expect: 1,
});
expect(res.applied).toBe(true);
expect(res.moved).toHaveLength(2);
expect(res.references.inboundFiles).toEqual(["Notes/Ref.md"]);
});
test("a strict mutation without --expect is refused before anything moves", async () => {
note("Projects/Old/a.md", "x\n");
note("Notes/Ref.md", "[[Projects/Old/a]]\n");
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
strict: true,
}),
).rejects.toThrow();
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
});
});
describe("the folder result's evidence tail", () => {
test("an applied move claims the detached index refresh and reports the index evidence", async () => {
note("Projects/Old/a.md", "alpha\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.references.index.state.length).toBeGreaterThan(0);
expect(res.references.index.nextCommand.length).toBeGreaterThan(0);
expect(res.references.refresh).toBeDefined();
// A relocation destroys nothing, so no snapshot is taken - the field
// is null for shape parity with the file surface, and the verdict
// covers the REWRITE.
expect(res.snapshot).toBeNull();
expect(res.recoverability.state.length).toBeGreaterThan(0);
});
test("a plan-only run claims nothing and refused nothing", async () => {
note("Projects/Old/a.md", "alpha\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
});
expect(res.references.refresh).toBeDefined();
expect(res.references.refreshReason).toBeNull();
});
});
describe("the file surface keeps refusing folder subjects", () => {
test("noteLifecycle refuses a folder path - it has no .md rung to pass", async () => {
mkdirSync(join(vault, "Projects/Old"), { recursive: true });
await expect(
noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.rename,
path: "Projects/Old",
to: "Projects/New",
apply: true,
}),
).rejects.toThrow(/\.md/);
await expect(
noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: "Projects/Old",
apply: true,
confirm: true,
}),
).rejects.toThrow(/\.md/);
expect(readdirSync(join(vault, "Projects"))).toContain("Old");
});
test("noteLifecycle refuses the folder actions by name - the machinery is two modules", async () => {
note("Projects/a.md", "x\n");
// One vocabulary, two machines: `move-folder` sent to the FILE surface
// must not fall through to the file envelope and report a one-file
// result for a many-file operation.
await expect(
noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/a.md",
to: "Elsewhere",
apply: true,
}),
).rejects.toThrow(/wrong_action|folder action/);
await expect(
noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.renameFolder,
path: "Projects/a.md",
to: "Renamed",
apply: true,
}),
).rejects.toThrow(NoteLifecycleError);
expect(existsSync(join(vault, "Projects/a.md"))).toBe(true);
});
});
/**
* The move set is judged by REAL LOCATION (H2, M18): the vault walk lists
* a file under whichever alias of its directory won the walk, so both the
* membership decision and the spelling every report and rewrite pair
* carries are decided by where a file really lives - inside the source's
* real path - never by the spelling the walk happened to reach it
* through. The two alias orders below are written to hold regardless of
* which spelling wins the walk on any host.
*/
describe("symlinked entries in the move set (judged by real location)", () => {
test("a symlinked directory inside the source excludes the foreign notes it reaches (H2, order one)", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Alpha/Deep/real.md", "real body\n");
note("Index.md", "[[Projects/Old/a]] and [[Alpha/Deep/real]]\n");
symlinkSync(join(vault, "Alpha/Deep"), join(vault, "Projects/Old/link"), "dir");
// The plan already shows the truth: only the folder's OWN note moves.
const plan = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
});
expect(plan.applied).toBe(false);
expect(plan.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.applied).toBe(true);
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
// The foreign note keeps its real location under either walked
// spelling, and no name for it appears at the destination.
expect(existsSync(join(vault, "Alpha/Deep/real.md"))).toBe(true);
expect(existsSync(join(vault, "Archive/Old/link/real.md"))).toBe(false);
// The link itself is neither followed nor removed: it is the residue,
// named like any other entry the move could not carry.
expect(res.leftBehind).toEqual(["link"]);
expect(existsSync(join(vault, "Projects/Old/link"))).toBe(true);
// The foreign note's inbound link is untouched; the moved note's is
// rewritten. Before the real-location judgment the foreign note was
// relocated under the link spelling with NO rewrite pair, and
// `[[Alpha/Deep/real]]` dangled.
expect(read("Index.md")).toBe("[[a]] and [[Alpha/Deep/real]]\n");
});
test("an alias walked before the source is normalized to the real spelling, not a silent no-op (H2, order two)", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Index.md", "[[Projects/Old/a]]\n");
// `Zed` sorts after `Projects`, so the walk reaches the source THROUGH
// the alias first and lists the note under the alias spelling only -
// the order that used to leave `movingSet` empty and report
// applied:true with nothing moved.
mkdirSync(join(vault, "Zed"), { recursive: true });
symlinkSync(join(vault, "Projects/Old"), join(vault, "Zed/alias"), "dir");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.applied).toBe(true);
// The move set carries the REAL spelling - the name the disk answers
// to and the name inbound links are spelled with - so the rewrite
// pair exists and `[[Projects/Old/a]]` does not dangle.
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(false);
expect(read("Index.md")).toBe("[[a]]\n");
// The source folder genuinely emptied and went; the operator's own
// alias is the only thing left pointing at a former address.
expect(existsSync(join(vault, "Projects/Old"))).toBe(false);
expect(res.leftBehind).toEqual([]);
});
test("a symlinked note is excluded and named, never hard-linked (M18)", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Other/x.md", "elsewhere\n");
// A RELATIVE target, the shape that dangles when the symlink itself is
// hard-linked at a new depth.
symlinkSync("../../Other/x.md", join(vault, "Projects/Old/l.md"));
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.applied).toBe(true);
expect(res.moved).toEqual([{ from: "Projects/Old/a.md", to: "Archive/Old/a.md" }]);
// The symlinked note is named as what stayed...
expect(res.leftBehind).toEqual(["l.md"]);
expect(lstatSync(join(vault, "Projects/Old/l.md")).isSymbolicLink()).toBe(true);
// ...and no name for it was created at the destination: linking the
// symlink used to leave a dangling `Archive/Old/l.md` behind.
expect(lstatSync(join(vault, "Archive/Old/l.md"), { throwIfNoEntry: false })).toBeUndefined();
// The real target is untouched at its real location.
expect(read("Other/x.md")).toBe("elsewhere\n");
});
test("a dangling name a mid-set fault created is dropped by the cleanup (M18)", async () => {
note("Projects/Old/a.md", "alpha\n");
// The relocation seam leaves a SYMLINK at the destination name whose
// target does not exist - the exact shape a hard-linked symlinked
// note produced - and then reports the fault. `existsSync` follows
// the link, sees nothing and skips the unlink; a name this call
// created must be dropped even when it dangles.
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
relocate: (fromAbs, toAbs, label) => {
symlinkSync(join(fromAbs, "../never-here.md"), toAbs);
throw new Error(`noteLifecycle: write of ${label} reported success but the file is absent`);
},
});
expect(res.applied).toBe(true);
expect(res.moved).toEqual([]);
expect(res.moveFailures).toHaveLength(1);
expect(res.moveFailures[0]!.path).toBe("Projects/Old/a.md");
expect(lstatSync(join(vault, "Archive/Old/a.md"), { throwIfNoEntry: false })).toBeUndefined();
expect(existsSync(join(vault, "Archive/Old"))).toBe(false);
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
});
});
/**
* The destination is judged by real path on both sides (M15), and the
* rename-intent heuristic only fires when the named destination directory
* does not exist (M16).
*/
describe("the destination's real path and existence", () => {
test("a destination that is a symlink alias of the source is refused as nesting (M15)", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Index.md", "[[Projects/Old/a]]\n");
mkdirSync(join(vault, "Aa/Deep"), { recursive: true });
symlinkSync(join(vault, "Projects/Old"), join(vault, "Aa/Deep/Link"), "dir");
for (const apply of [false, true]) {
let caught: unknown;
try {
await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Aa/Deep/Link",
apply,
});
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(NoteLifecycleError);
const refusal = caught as NoteLifecycleError;
expect(refusal.code).toBe("destination_inside_source");
expect(refusal.message).toContain("Projects/Old");
}
// Nothing was linked into the source: the alias spelled a path
// outside the folder while naming the folder itself, and the spelled
// guard used to let it fold `Old/` inside `Projects/Old`.
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/Old"))).toBe(false);
expect(read("Index.md")).toBe("[[Projects/Old/a]]\n");
});
test.skipIf(!FOLDS_CASE)(
"a case-folded destination inside the source is refused by real path (M15)",
async () => {
note("Projects/Old/a.md", "alpha\n");
// On the folding host this IS `Projects/Old/sub/deeper` - inside the
// source but not the source itself - although its spelling never
// matches the spelled guard. (A destination folding onto the source
// itself is the destination_unchanged refusal, covered elsewhere.)
mkdirSync(join(vault, "projects/old/sub/deeper"), { recursive: true });
let caught: unknown;
try {
await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "projects/old/sub/deeper",
apply: true,
});
} catch (err) {
caught = err;
}
// On a case-sensitive host the spelled rung refuses (the spelled
// destination realpaths strictly inside the source); on a folding
// host the platform realpath preserves the caller's casing, so the
// refusal comes from the identity rung - the directory entry IS the
// source. Either way the code is the same.
expect(caught).toBeInstanceOf(NoteLifecycleError);
expect((caught as NoteLifecycleError).code).toBe("destination_inside_source");
expect(existsSync(join(vault, "Projects/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/sub/Old"))).toBe(false);
},
);
test("a move into an EXISTING sibling folder works in one call (M16)", async () => {
note("Projects/Old/a.md", "alpha\n");
note("Projects/Old/b.md", "beta\n");
note("Index.md", "[[Projects/Old/a]]\n");
mkdirSync(join(vault, "Projects/Archive"), { recursive: true });
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Projects/Archive",
apply: true,
});
// An existing sibling directory is a real move target, not the
// spelling of a rename intent - the refusal that pointed at
// rename-folder (which points back here for a cross-parent move)
// used to make this move impossible in one call.
expect(res.applied).toBe(true);
expect(res.to).toBe("Projects/Archive/Old");
expect(res.moved.map((m) => m.to).toSorted()).toEqual([
"Projects/Archive/Old/a.md",
"Projects/Archive/Old/b.md",
]);
expect(existsSync(join(vault, "Projects/Old"))).toBe(false);
expect(read("Index.md")).toBe("[[a]]\n");
});
test("a NON-existent sibling destination is still the rename-intent refusal (M16)", async () => {
note("Projects/Second/c.md", "c\n");
await expect(
folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Second",
to: "Projects/Nowhere",
apply: true,
}),
).rejects.toThrow(/use rename-folder/);
expect(existsSync(join(vault, "Projects/Second/c.md"))).toBe(true);
});
});
/**
* Only Markdown moves; the receipt says what that honestly costs (M17):
* a moved note's RELATIVE Markdown links and images depend on the note's
* directory, which the move changed, and when the target stayed behind
* the receipt names the pair instead of letting `files_rewritten: 0`
* read as "nothing broke".
*/
describe("relative links the move leaves dangling (M17)", () => {
test("a moved note's relative embed whose target stayed behind is named; targets that moved are not", async () => {
note(
"Projects/Old/a.md",
"\n" +
"[nested](./sub/other.md)\n" +
"\n" +
"[remote](https://example.com/x.png)\n" +
"\n",
);
note("Projects/Old/sub/other.md", "nested\n");
writeFileSync(join(vault, "Projects/Old/diagram.png"), "png\n");
// The plan previews the same judgment from the planned set.
const plan = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
});
expect(plan.applied).toBe(false);
expect(plan.danglingRelativeLinks).toEqual([
{ note: "Archive/Old/a.md", target: "diagram.png" },
]);
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.applied).toBe(true);
// The embed whose target is not a note stayed behind - named per note
// and target, exactly as the note spells it.
expect(res.danglingRelativeLinks).toEqual([
{ note: "Archive/Old/a.md", target: "diagram.png" },
]);
// The attachment itself is in the residue, the file surface's own
// honest answer for what a Markdown-only move leaves.
expect(res.leftBehind).toEqual(["diagram.png"]);
expect(existsSync(join(vault, "Archive/Old/a.md"))).toBe(true);
expect(existsSync(join(vault, "Projects/Old/diagram.png"))).toBe(true);
// A target that moved WITH the folder still resolves and is not
// named; a vault-absolute or scheme spelling never depended on the
// note's directory; a link that was already dangling is not this
// operation's doing.
expect(existsSync(join(vault, "Archive/Old/sub/other.md"))).toBe(true);
});
test("a move whose relative targets all move with it names no dangling links", async () => {
note("Projects/Old/a.md", "\n");
note("Projects/Old/img/keep.md", "the target set is Markdown, so this moves too\n");
const res = await folderLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.moveFolder,
path: "Projects/Old",
to: "Archive",
apply: true,
});
expect(res.moved).toHaveLength(2);
expect(res.danglingRelativeLinks).toEqual([]);
});
});