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 lifecycle (`./lifecycle.ts`) is defined per FILE: re-
* organizing a vault by folder means moving notes one at a time through a
* surface that refuses any directory change, which is how inbound
* path-spelled wikilinks break by hand. This module moves a whole folder
* in one call on the SAME terms the file surface set: the same path
* envelope minus the `.md` rung, the same link-assert-unlink relocation,
* the same count guard, the same dry-run default, and the same settled
* partial-failure doctrine - a mid-set failure is NAMED, never rolled
* back.
*
* ## The envelope has one rung less, and nothing else
*
* `resolveNoteTarget` requires a `.md` suffix, which a folder cannot
* carry; every other rung is mirrored here rung for rung: vault-relative
* (no absolute path), separators this host reads the way the caller wrote
* them, no `..` traversal, not the `Brain/` machinery root (on the
* spelled and the realpath alike, case-insensitively), vault-scope
* checks, the operator's write binding, inside the vault. The SOURCE must
* additionally stat as a directory - `source_missing`, the refusal a
* path with no folder gets - and the vault root is refused as a subject.
*
* ## Why one rewrite pass is genuinely complete here
*
* A folder move never changes a basename. The bare `[[Name]]` spelling
* resolved by carrier count before the move and resolves by the same
* carrier count after it - the carriers moved, the count did not - so
* `decideBasename`'s whole question does not arise and the bare-name
* repair pass the file surface needs has nothing to do. Only PATH-spelled
* links (`[[Projects/Old/a]]`, `[[Projects/Old/a.md]]`) break, and ONE
* `retargetWikilinks` call over all pairs - minimal spellings computed
* against the post-move population - fixes them, including links inside
* the moved folder, because the pass matches text rather than live paths.
*
* ## Nothing here is atomic, and the report says where it split
*
* The move set is the vault's MARKDOWN, the same population every
* lifecycle surface addresses (`retargetWikilinks`'s own walk produces
* it): other files are not notes, are not moved, and are not this
* operation's business. A folder whose subtree holds them reports the
* Markdown relocations honestly in `moved` and leaves the rest standing
* - the prune at the end removes only what the moves genuinely emptied.
* And the set is judged by REAL LOCATION, never by the spelling the walk
* happened to reach a file through: the walk lists a note under whichever
* alias of its directory won the walk, so a move set built from spellings
* would relocate another folder's notes through a symlinked directory
* inside the source, or read as an empty applied success when an alias
* elsewhere was walked first. Membership - and the spelling every move
* pair and rewrite pair carries - is decided by where a file really
* lives: inside the source's real path, under the source's real name. A
* symlinked directory inside the source therefore relocates none of the
* foreign notes it reaches (the link is the named residue), a symlinked
* note is left standing rather than hard-linking its target, and a
* source reached through an alias is moved, reported and pruned under
* the name its bytes actually answer to.
*
* Relative Markdown links and images are NOT wikilinks and get no
* rewrite - the pass repairs `[[path]]` spellings only, and a relative
* `` depends on the note's directory, which the move
* changed. When a moved note's relative target stayed behind, the
* receipt names the pair in `danglingRelativeLinks` instead of letting
* `files_rewritten: 0` read as "nothing broke".
*
* Occupancy is eliminated up front: every destination file path, and the
* destination folder itself, is checked (with the dev/ino case-only
* exemption) BEFORE the first rename, and an occupied destination refuses
* naming every collision with nothing moved. What the pre-flight cannot
* eliminate is a mid-set I/O fault, and rolling one back would mean
* unlinking already-moved destination names - new destructive behavior
* the snapshot gate does not cover. So the set continues and the result
* reports the split point exactly: `moved` is what relocated,
* `moveFailures` is what did not and why, and EVERYTHING downstream - the
* rewrite pairs, the spellings reported - is computed from the
* successfully moved set only. A file that failed to move keeps its old
* path, its inbound links stay correct, and no pair of theirs enters the
* pass. Relocations are byte-preserving and destroy nothing, so - as on
* the file surface - no destructive snapshot is taken for a move.
*/
import {
existsSync,
lstatSync,
mkdirSync,
readFileSync,
readdirSync,
rmdirSync,
statSync,
unlinkSync,
type Dirent,
type Stats,
} from "node:fs";
import { dirname, join, posix, sep, win32 } from "node:path";
import { checkWriteBinding } from "../../write-binding/index.ts";
import { ensureInsideVault, realVaultRelative, toPosix } from "../../path-safety.ts";
import { pathCovers } from "../../vault-scope/defaults.ts";
import { assertExpectedCount } from "../count-guard.ts";
import { classifyRecoverability, type RecoverabilityVerdict } from "../gates/recoverability.ts";
import { minimalSpellingFor } from "../link-graph/minimal-spelling.ts";
import { retargetWikilinks } from "../page-dedup.ts";
import { BRAIN_LOG_REL, BRAIN_CONFIG_FILE, BRAIN_ROOT_REL, isUnderBrainRoot } from "../paths.ts";
import { viewFolderRefusal } from "../../view/vault-guard.ts";
import { BrainConfigError } from "../policy.ts";
import { requireNextStep } from "../next-step.ts";
import { assertNoteVaultForWrite } from "../../vault-adapter/index.ts";
import {
inspectPath,
resolveVaultScope,
type InspectResult,
type VaultScope,
} from "../../vault-scope/index.ts";
import {
BASENAME_REWRITE,
INDEX_REFRESH,
namesSameEntry,
NOTE_LIFECYCLE_ACTION,
NoteLifecycleError,
readIndexEvidence,
relocateFileBytes,
type IndexEvidence,
type IndexRefresh,
type NoteLifecycleAction,
type NoteReferenceReport,
} from "./lifecycle.ts";
// The claim itself is NOT re-exported by `./lifecycle.ts` (only the
// vocabulary and the evidence read are, for reporters): sibling writers
// import it from the module that owns it, exactly as the create and
// content-update writers do.
import { claimPostWriteRefresh } from "./index-refresh.ts";
import { CreateNoteError, NOTE_CONFIG_INVALID_CODE } from "./create-note.ts";
// ----- What a caller may ask for --------------------------------------------
/**
* The folder actions, spelled by the ONE lifecycle vocabulary
* (`NOTE_LIFECYCLE_ACTION`) so the CLI guard, the MCP enum and the
* manifest cannot drift apart. The file actions refuse a folder subject
* (their envelope requires `.md`), and this surface refuses the file
* actions by name: `delete` and `archive` are decisions about a FILE, and
* running them over a directory would invent new destructive behavior
* this module does not own.
*/
export const FOLDER_LIFECYCLE_ACTION = Object.freeze({
/** Move a whole folder under a destination parent. */
moveFolder: NOTE_LIFECYCLE_ACTION.moveFolder,
/** Rename a whole folder within its parent. */
renameFolder: NOTE_LIFECYCLE_ACTION.renameFolder,
} as const);
/** Closed union over {@link FOLDER_LIFECYCLE_ACTION}. */
export type FolderLifecycleAction =
(typeof FOLDER_LIFECYCLE_ACTION)[keyof typeof FOLDER_LIFECYCLE_ACTION];
/** Membership list. */
export const FOLDER_LIFECYCLE_ACTIONS: ReadonlyArray<FolderLifecycleAction> = Object.freeze(
Object.values(FOLDER_LIFECYCLE_ACTION),
);
/**
* `unknown` rather than `string`: the value arrives as an untyped MCP
* argument or a raw CLI positional, exactly like
* {@link isNoteLifecycleAction}, whose census probing this guard shares.
*/
export function isFolderLifecycleAction(value: unknown): value is FolderLifecycleAction {
return (
typeof value === "string" && (FOLDER_LIFECYCLE_ACTIONS as ReadonlyArray<string>).includes(value)
);
}
// ----- Inputs, results, refusals --------------------------------------------
export interface FolderLifecycleInput {
/** `move-folder` or `rename-folder`; every other action is refused. */
readonly action: NoteLifecycleAction;
/** Vault-relative path of the subject folder. */
readonly path: string;
/**
* `move-folder`: the vault-relative destination DIRECTORY (the folder
* lands under it, keeping its name). `rename-folder`: the new single-
* segment name, under the same parent. Required for both.
*/
readonly to?: string;
/** False (the default) walks, counts and writes nothing. */
readonly apply?: boolean;
/** `--expect N`: assert the inbound-reference count before any write. */
readonly expect?: number | null;
/** `--strict`: refuse a mutation carrying no `--expect` guard. */
readonly strict?: boolean;
/** Injected clock, forwarded to the recovery claim so a run stays reproducible. */
readonly now?: Date;
/**
* May the caller read the vault file at this vault-relative path? One
* they may not is reported as a vault without it would be - absent
* from `inboundFiles`, `filesScanned` and `rewriteFailures` - the same
* rule the file surface's `readable` documents. The reach judges the
* MOVE SET as well: a folder holding any note the caller may not read
* is refused exactly as a missing folder, so neither the plan nor the
* apply can name, count or relocate a page past the caller's reach. A
* folder with no Markdown at all has no page to judge and moves.
* Absent, every file counts (the CLI, which reads the vault directly).
*/
readonly readable?: (rel: string) => boolean;
/** Test seam: replaces the detached spawn of the post-write index refresh. */
readonly refreshSpawn?: (argv: string[]) => void;
/**
* Test seam: the byte relocation itself, defaulting to the shared
* {@link relocateFileBytes}. A stand-in produces faults the host cannot
* schedule deterministically - a foreign file appearing at a destination
* name the pre-flight had cleared, the exact race the occupied-name
* guard exists for.
*/
readonly relocate?: typeof relocateFileBytes;
/**
* The config file the post-write refresh resolves the search config
* through - the caller's `--config` (or the MCP server's config path).
*/
readonly refreshConfigPath?: string;
}
/** One file that relocated. */
export interface FolderMovedPath {
/** Vault-relative path the file was at. */
readonly from: string;
/** Vault-relative path it is at now. */
readonly to: string;
}
/** One file the set could not relocate, with the filesystem's reason. */
export interface FolderMoveFailure {
/** Vault-relative path the file KEEPS - it never moved. */
readonly path: string;
/** The filesystem's own message, never a re-description of it. */
readonly reason: string;
}
/** One relative link or image in a moved note whose target stayed behind. */
export interface FolderDanglingLink {
/**
* The moved note, spelled at its NEW path - where the broken spelling
* now lives.
*/
readonly note: string;
/** The relative target, spelled exactly as the note spells it. */
readonly target: string;
}
export interface FolderLifecycleResult {
readonly action: FolderLifecycleAction;
/** Vault-relative path the folder was at. */
readonly from: string;
/** Vault-relative path it is at now. */
readonly to: string;
/** False when this was a plan-only run. */
readonly applied: boolean;
/**
* Every file that relocated, sorted by its old path. A plan-only run
* relocates nothing and reports the PLANNED set here - the preview the
* apply would carry out - so an empty list always means an empty move
* set, never an unapplied one; {@link FolderLifecycleResult.applied}
* carries that distinction.
*/
readonly moved: ReadonlyArray<FolderMovedPath>;
/**
* Every file that did not relocate, with why. Non-empty means the
* operation is HALF-APPLIED: the rewrite pairs were computed from
* {@link FolderLifecycleResult.moved} only, so each failure's inbound
* links still name the path its bytes are actually at. Never rolled
* back - see the module header for why that is the better half-state.
*/
readonly moveFailures: ReadonlyArray<FolderMoveFailure>;
/**
* What stayed in the source folder after the prune, from a readdir of
* it once the prune had done its best. The move set is the vault's
* MARKDOWN, so a subtree that also holds anything else - an image
* beside the notes, a file the moves could not relocate - keeps its
* source folder, and without this field the result would read as if
* the folder went with its notes. Empty (and absent on the rendered
* surfaces) means nothing was left behind: the folder itself is gone.
* A plan-only run relocates nothing, so it leaves nothing behind
* either.
*/
readonly leftBehind: ReadonlyArray<string>;
/**
* The moved notes' RELATIVE Markdown links and images that no longer
* resolve: targets the move did not carry (the set is the vault's
* MARKDOWN) and that stayed behind in the source folder. The rewrite
* pass repairs `[[path]]` spellings only, so without this field a
* `files_rewritten: 0` would read as "nothing broke" while every moved
* note's relative embed pointed at nothing. A target that moved with
* its note 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. A plan reports the
* same judgment for its planned set. Empty (and absent on the rendered
* surfaces) when nothing dangles.
*/
readonly danglingRelativeLinks: ReadonlyArray<FolderDanglingLink>;
/** What the recovery point (if any) is worth for THIS operation. */
readonly recoverability: RecoverabilityVerdict;
/**
* Always `null`, kept for shape parity with the file result: a
* relocation destroys nothing, so no recovery point is taken for a
* move. The REWRITE's risk is what {@link FolderLifecycleResult.recoverability}
* grades, exactly as on the file surface.
*/
readonly snapshot: null;
/** What happened to inbound references, and on what evidence. */
readonly references: NoteReferenceReport;
}
// ----- The folder envelope: resolveNoteTarget minus the `.md` rung ----------
/** The separator that is structure on Windows and a filename character elsewhere. */
const FOLDER_WINDOWS_SEP = win32.sep;
/** Registry code for a vault whose Brain config does not load. */
const FOLDER_CONFIG_INVALID_EXIT = requireNextStep(NOTE_CONFIG_INVALID_CODE).nextCommand;
/** Vault-relative spelling of the config file every refusal here names. */
const BRAIN_CONFIG_REL = posix.join(BRAIN_ROOT_REL, BRAIN_CONFIG_FILE);
/**
* Translate a Brain config failure into this surface's typed refusal -
* the same composition `resolveNoteTarget` uses, so a malformed config
* reads the same on whichever surface reaches it first.
*/
function withConfigFault<T>(read: () => T): T {
try {
return read();
} catch (err) {
if (err instanceof BrainConfigError) {
throw new CreateNoteError(
"config_invalid",
`${BRAIN_CONFIG_REL}: ${err.message}; ${FOLDER_CONFIG_INVALID_EXIT}`,
);
}
throw err;
}
}
/**
* Refuse a caller-named path whose separators this host does not read the
* way the caller wrote them - the same refusal `resolveNoteTarget` makes,
* for the same reason: normalising `\` would silently reinterpret the
* caller's string into a path it did not send.
*/
function assertHostPathSeparators(path: string): void {
if (FOLDER_WINDOWS_SEP === sep) return;
if (!path.includes(FOLDER_WINDOWS_SEP)) return;
throw new CreateNoteError(
"invalid_path",
`folder path must use '${posix.sep}' to separate segments; on this host ` +
`'${FOLDER_WINDOWS_SEP}' is an ordinary filename character, so the path would not ` +
`mean what it looks like: ${path}`,
);
}
/** The refusal sentence for a path vault scope rejects - `create-note.ts`'s wording. */
function scopeRefusal(scope: VaultScope, inspected: InspectResult): string {
if (inspected.reason === "not-included") {
return `path is outside vault.include_paths (${(scope.includePaths ?? []).join(", ")})`;
}
return `path is excluded by vault.ignore_paths (${inspected.rule?.raw ?? "rule"})`;
}
/**
* A folder path resolved through the shared write safety envelope: the
* exact ladder {@link resolveNoteTarget} runs, minus the `.md` rung a
* folder cannot pass. Both the source folder and the destination folder
* go through it, so a destination cannot reach somewhere a note could not
* live.
*
* `allowVaultRoot` relaxes exactly one rung, for exactly one caller: the
* destination DIRECTORY of a `move-folder` may be the vault root, because
* a folder may land at the top level - while the root itself stays
* refused as a SUBJECT (a subject is what moves; the root is what
* everything moves within).
*/
function resolveFolderTarget(
vault: string,
path: string,
opts: { readonly allowVaultRoot?: boolean } = {},
): { relPath: string; abs: string } {
if (path.startsWith(posix.sep) || path.startsWith(FOLDER_WINDOWS_SEP)) {
throw new CreateNoteError("invalid_path", `folder path must be vault-relative: ${path}`);
}
assertHostPathSeparators(path);
const scope = withConfigFault(() => resolveVaultScope(vault));
let inspected;
try {
inspected = inspectPath(path, scope, vault);
} catch (err) {
throw new CreateNoteError("invalid_path", err instanceof Error ? err.message : String(err));
}
const relPath = inspected.relPath;
// The vault root (`""`, or a spelling `inspectPath` normalises to it)
// is the whole vault: moving or renaming it is not a folder operation,
// and pretending otherwise would report a move of every note in the
// vault under one `moved` count.
if (relPath === "" && opts.allowVaultRoot !== true) {
throw new CreateNoteError(
"invalid_path",
`the vault root is not a folder subject: ${path === "" ? "(empty path)" : path}`,
);
}
if (relPath === "") {
// Reachable only with `allowVaultRoot`: the destination directory IS
// the vault, inside it by definition, with no realpath or binding
// rung of its own left to run - every file that lands beneath it
// resolves through a full pass of its own.
return { relPath: "", abs: ensureInsideVault(vault, vault) };
}
if (isUnderBrainRoot(relPath)) {
throw new CreateNoteError(
"excluded",
`the Brain machinery root is not writable via the folder lifecycle: ${relPath}`,
);
}
let landsAt: string | null;
try {
landsAt = realVaultRelative(vault, relPath);
} catch (err) {
const code = (err as NodeJS.ErrnoException)?.code ?? "unknown";
throw new CreateNoteError(
"invalid_path",
`folder path cannot be resolved (${code}): ${relPath}`,
);
}
if (landsAt === null) {
throw new CreateNoteError(
"outside_vault",
`folder path resolves outside the vault: ${relPath}`,
);
}
if (isUnderBrainRoot(landsAt)) {
throw new CreateNoteError(
"excluded",
`the Brain machinery root is not writable via the folder lifecycle: ${relPath} resolves to ${landsAt}`,
);
}
// The human view folder in the vault is the view writer's
// (`core/view/vault-guard.ts`): no folder moves into or out of it.
for (const rel of new Set([relPath, landsAt])) {
const viewRefusal = viewFolderRefusal(vault, rel, "the folder lifecycle");
if (viewRefusal !== null) throw new CreateNoteError("excluded", viewRefusal);
}
if (inspected.excluded) {
throw new CreateNoteError("excluded", `${scopeRefusal(scope, inspected)}: ${relPath}`);
}
const refusal = withConfigFault(() => checkWriteBinding(vault, relPath));
if (refusal !== null) {
throw new CreateNoteError("write_binding", refusal.message);
}
let abs: string;
try {
abs = ensureInsideVault(join(vault, relPath), vault);
} catch (err) {
throw new CreateNoteError("outside_vault", err instanceof Error ? err.message : String(err));
}
// The folder envelope speaks POSIX: every judgment below compares or
// slices relPath against real locations and walk spellings, which are
// POSIX spellings on every platform. `inspectPath` joins its segments
// with the platform separator, so without this rung a Windows relPath
// carries backslashes and the spelled guards (`startsWith(`${rel}/`)`)
// silently stop matching - the destination-inside-source refusal never
// fires and the move nests the folder into itself on a case-folding
// host.
return { relPath: toPosix(relPath), abs };
}
// ----- Path helpers (folder-shaped) -----------------------------------------
/** `Projects/Old` -> `Old`. */
function folderBasename(relPath: string): string {
return relPath.split(posix.sep).at(-1) ?? relPath;
}
/** `Projects/Old` -> `Projects`, and `Old` -> `""`. */
function folderParent(relPath: string): string {
const cut = relPath.lastIndexOf(posix.sep);
return cut < 0 ? "" : relPath.slice(0, cut);
}
/** The `.md` suffix, matched case-insensitively. */
const MARKDOWN_SUFFIX = ".md";
/** `Projects/Old/a.md` -> `Projects/Old/a`. */
function withoutSuffix(relPath: string): string {
return relPath.toLowerCase().endsWith(MARKDOWN_SUFFIX)
? relPath.slice(0, -MARKDOWN_SUFFIX.length)
: relPath;
}
/** `statSync`, or `null` when the path is not there or cannot be read. */
function statOrNull(target: string): Stats | null {
try {
return statSync(target);
} catch {
return null;
}
}
/**
* `lstatSync`, or `null` when the NAME is not there or cannot be read.
* Unlike `statSync`/`existsSync` this judges the name itself, so a
* symlink whose target is gone - a name this call created and then
* reported as failed - still counts as present and can be dropped.
*/
function lstatOrNull(target: string): Stats | null {
try {
return lstatSync(target);
} catch {
return null;
}
}
/**
* The spelling the disk answers to: `relPath`'s real vault-relative
* location, or the caller's spelling when that does not resolve (the
* vault root, or a path whose deepest existing ancestor already carries
* the answer). Every path this module JUDGES, MOVES or REPORTS goes
* through it, so a symlink alias cannot make one folder look like two:
* the review's H2/M15 faults were both spelling comparisons where one
* side was an alias.
*/
function realSpelling(vault: string, relPath: string): string {
return realVaultRelative(vault, relPath) ?? relPath;
}
/**
* Whether the folder's REAL subtree holds any Markdown file: a plain
* readdir that never follows a symlinked entry, because a link's name is
* not a Markdown file of this subtree - its target's real location is
* somewhere else (or nowhere) and is judged there. This is the disk's
* own answer for the empty-move-set refusal, independent of what the
* vault walk happened to list.
*/
function subtreeHoldsMarkdown(vault: string, fromRel: string): boolean {
const stack: string[] = [join(vault, fromRel)];
while (stack.length > 0) {
const dir = stack.pop()!;
let entries: Dirent[];
try {
entries = readdirSync(dir, { withFileTypes: true });
} catch {
continue;
}
for (const entry of entries) {
if (entry.isSymbolicLink()) continue;
if (entry.isDirectory()) {
stack.push(join(dir, entry.name));
continue;
}
if (entry.isFile() && entry.name.toLowerCase().endsWith(MARKDOWN_SUFFIX)) return true;
}
}
return false;
}
/** `readdirSync`, or `null` when the directory cannot be read. */
function readdirOrNull(target: string): string[] | null {
try {
return readdirSync(target);
} catch {
return null;
}
}
/**
* Subtrees the rewrite pass READS and REPORTS but never rewrites - the
* file surface's one entry, shared for the same reason: `Brain/log` is an
* append-only record of what an agent said at an instant, and repairing
* testimony changes what it says was said.
*/
const APPEND_ONLY_REL: ReadonlyArray<string> = Object.freeze([BRAIN_LOG_REL]);
/** The walk root the reference scan and the move-set planning share: the whole vault. */
const VAULT_ROOT_REL = "";
/** Where one planned file goes, with the dev/ino answer for its destination name. */
interface PlannedMove {
readonly fromRel: string;
readonly toRel: string;
readonly fromAbs: string;
readonly toAbs: string;
/** The case-only folder rename: destination name IS the source entry. */
readonly sameEntry: boolean;
}
// ----- Destination resolution -----------------------------------------------
/**
* Resolve the destination FOLDER this action implies, through the same
* envelope as the source, and refuse the caller mistakes the file
* surface's rename/move split exists to catch - at folder granularity:
* `move-folder` must change the folder's parent, `rename-folder` must
* keep it.
*
* Both judgments run on REAL paths, never on spellings. The source
* arrives already normalized to the name its bytes answer to; the
* destination directory is normalized here before anything is decided,
* because a symlink alias spells a path outside the source while naming
* the source itself (or something inside it) - the inside-source guard
* comparing spellings let such a destination fold the folder into
* itself, and a case-folded spelling slipped past the same way. The
* landing path is reported in its real spelling too, so the receipt
* names where the bytes actually went.
*
* The rename-intent heuristic for `move-folder` - a destination in the
* source's own parent is the spelling of a RENAME - applies ONLY when
* the named destination directory does not exist: an existing sibling
* directory is a real move target (moving `Projects/Old` under an
* existing `Projects/Archive`), and refusing it pointed at
* `rename-folder`, which refuses the cross-parent move right back. A
* sibling that is not there is exactly the caller mistake the heuristic
* exists for, so it is refused by name. The heuristic exempts the top
* level: a rename there spells a single segment, so `Old` under
* `Archive` can only ever mean the move it asked for, and refusing it
* would leave every top-level folder unmovable into a sibling
* top-level directory.
*/
function resolveFolderDestination(
vault: string,
input: FolderLifecycleInput,
source: { relPath: string; abs: string },
): { relPath: string; abs: string } {
if (input.to === undefined) {
throw new NoteLifecycleError(
"destination_required",
`${input.action} requires a destination ('to')`,
);
}
const action = input.action;
if (action === FOLDER_LIFECYCLE_ACTION.renameFolder) {
if (input.to.includes(posix.sep) || input.to.includes(FOLDER_WINDOWS_SEP)) {
// Refused as the caller mistake it is - a rename spelled across
// parents - not normalised into the move it did not ask for.
throw new NoteLifecycleError(
"wrong_action",
`rename-folder keeps the folder in ${folderParent(source.relPath) || "the vault root"}; ` +
`'${input.to}' crosses parents - use move-folder`,
);
}
}
/** The landing folder, judged and reported in its real spelling. */
const landing = (folder: { relPath: string; abs: string }): { relPath: string; abs: string } => {
const real = realSpelling(vault, folder.relPath);
return real === folder.relPath
? folder
: { relPath: real, abs: ensureInsideVault(join(vault, real), vault) };
};
if (action === FOLDER_LIFECYCLE_ACTION.moveFolder) {
const destinationDirectory = resolveFolderTarget(vault, input.to, { allowVaultRoot: true });
const destinationReal = realSpelling(vault, destinationDirectory.relPath);
// A destination directory inside the source's own subtree nests the
// tree inside itself: every planned path stays a strict descendant of
// the source, so the file-surface refusals (same path, same parent)
// all pass while the operation folds the folder into its own
// descendant. Refused on the destination DIRECTORY the caller named -
// the computed landing path is necessarily deeper still - and judged
// by real path on both sides, which is what an alias (or a case
// fold) cannot talk its way past.
if (destinationReal === source.relPath || destinationReal.startsWith(`${source.relPath}/`)) {
throw new NoteLifecycleError(
"destination_inside_source",
`${action} destination ${destinationDirectory.relPath} sits inside the source folder ` +
`${source.relPath} (it resolves on disk to ${destinationReal}); the folder would ` +
"nest inside itself",
);
}
// Spelling-independent rung: walk the destination chain up to the
// vault root and refuse when any existing entry IS the source's own
// directory entry. A file-identity compare is what a case fold, a
// Unicode normalization form or an alias cannot talk past - the
// spelled rungs above judge spellings, and a host that answers a
// spelled path from a differently spelled real entry can slip a
// mismatch past every one of them.
const sourceEntry = statOrNull(source.abs);
if (sourceEntry !== null && sourceEntry.ino !== 0) {
let cursor = destinationDirectory.abs;
for (;;) {
const entry = statOrNull(cursor);
if (entry !== null && entry.ino === sourceEntry.ino && entry.dev === sourceEntry.dev) {
throw new NoteLifecycleError(
"destination_inside_source",
`${action} destination ${destinationDirectory.relPath} is the source folder ` +
`${source.relPath} (same directory entry on this host); the folder would ` +
"nest inside itself",
);
}
const parent = dirname(cursor);
if (parent === cursor || parent === vault || parent.length < vault.length) break;
cursor = parent;
}
}
const destination = landing(
resolveFolderTarget(
vault,
posix.join(destinationDirectory.relPath, folderBasename(source.relPath)),
),
);
if (destination.relPath === source.relPath) {
throw new NoteLifecycleError(
"destination_unchanged",
`${action} destination is the source folder: ${source.relPath}`,
);
}
if (
statOrNull(destinationDirectory.abs) === null &&
folderParent(source.relPath) !== "" &&
folderParent(destinationReal) === folderParent(source.relPath)
) {
throw new NoteLifecycleError(
"wrong_action",
`move-folder changes the folder's parent; ${destinationDirectory.relPath} sits in ` +
`${folderParent(source.relPath) || "the vault root"}, where ${source.relPath} lives - ` +
`use rename-folder`,
);
}
return destination;
}
const destination = landing(
resolveFolderTarget(vault, posix.join(folderParent(source.relPath), input.to)),
);
if (destination.relPath === source.relPath) {
throw new NoteLifecycleError(
"destination_unchanged",
`${action} destination is the source folder: ${source.relPath}`,
);
}
return destination;
}
// ----- Occupancy pre-flight --------------------------------------------------
/**
* Check EVERY destination before the first rename and refuse naming every
* collision. Within-set collisions are impossible (the relative structure
* is preserved), so the only collisions are with pre-existing files and
* directories at the destination - and finding them all before anything
* moves is the closest thing to atomicity this operation honestly has.
* The check runs on the PLAN, so a zero-file move set is covered too: an
* empty folder whose destination path is taken by a FILE refuses exactly
* like a full one.
*
* A destination folder that exists is an occupancy unless it is EMPTY
* (the files land into it) or is the same directory entry as the SOURCE
* folder (the case-only folder rename). A destination FILE path is an
* occupancy unless it names the same entry as its source file - the
* case-only rename's per-file face.
*/
function assertDestinationsFree(
planned: ReadonlyArray<PlannedMove>,
sourceAbs: string,
destination: { relPath: string; abs: string },
): void {
const collisions: string[] = [];
const destinationStat = statOrNull(destination.abs);
if (destinationStat !== null && !destinationStat.isDirectory()) {
collisions.push(destination.relPath);
} else if (destinationStat !== null && !namesSameEntry(sourceAbs, destination.abs)) {
// An unreadable destination directory states nothing about emptiness,
// so it is an occupancy too - a move into it cannot be verified free,
// and a refusal names the directory rather than guessing.
const entries = readdirOrNull(destination.abs);
if (entries === null) collisions.push(`${destination.relPath} (could not be read)`);
else if (entries.length > 0) collisions.push(`${destination.relPath} (not empty)`);
}
for (const move of planned) {
const destinationStat = statOrNull(move.toAbs);
if (destinationStat === null) continue;
if (namesSameEntry(move.fromAbs, move.toAbs)) continue;
collisions.push(move.toRel);
}
if (collisions.length > 0) {
throw new NoteLifecycleError(
"destination_occupied",
`destinations already exist and nothing was moved: ${collisions.join(", ")}`,
);
}
}
// ----- What a Markdown-only move leaves dangling -----------------------------
/** Inline Markdown link/image target: `[text](target)`, ``. */
const MARKDOWN_LINK_TARGET_RE = /\[[^\]]*\]\(\s*<?([^)<>]+?)>?\s*\)/g;
/**
* The URI-scheme shape (`https:`, `obsidian:`, `mailto:`) that is an
* address rather than a path - the same judgment `path-safety.ts`'s
* unexported `URI_SCHEME_RE` makes for wikilink targets.
*/
const URI_SCHEME_TEST = /^[a-z][a-z0-9+.-]*:/i;
/**
* Which of the moved notes' RELATIVE Markdown links and images now point
* at nothing. The judgment is made for each target exactly as the note
* spells it, against the OLD directory the link was written to resolve
* from and the NEW one the note now lives at: the link dangles only when
* the target sat where the old spelling resolved to (it was never this
* operation's business otherwise) and sits nowhere where the new one
* does. A target that moved with the folder still resolves; a
* vault-absolute (`/pic.png`) or scheme spelling never depended on the
* note's directory; an in-page `#anchor` names the note itself; a link
* that was already dangling names no fault of the move. Each distinct
* note-and-target pair is named once, sorted by note then target.
*/
function danglingRelativeLinks(
vault: string,
moves: ReadonlyArray<{
readonly from: string;
readonly to: string;
/** Where the note's bytes are right now - the old path on a plan, the new one on an apply. */
readonly bytesAbs: string;
}>,
/**
* PLAN only: the move-set's own promise that a Markdown target sitting
* inside the source will be at the new location once the move runs.
* An apply needs no promise - the relocation has already happened and
* the disk is the whole truth - but a plan that judged by the current
* disk would name EVERY relative target dangling, because nothing has
* landed yet.
*/
willLand?: (oldRel: string) => boolean,
): FolderDanglingLink[] {
const seen = new Set<string>();
const out: FolderDanglingLink[] = [];
for (const move of moves) {
let body: string;
try {
body = readFileSync(move.bytesAbs, "utf8");
} catch {
// A note that cannot be read states nothing about its links; the
// per-file machinery has already named it if the move failed.
continue;
}
for (const match of body.matchAll(MARKDOWN_LINK_TARGET_RE)) {
const raw = match[1]!;
if (raw === "" || raw.startsWith("#") || raw.startsWith("/") || URI_SCHEME_TEST.test(raw)) {
continue;
}
const target = (() => {
try {
return decodeURIComponent(raw);
} catch {
return raw;
}
})();
const hash = target.indexOf("#");
const pathPart = hash < 0 ? target : target.slice(0, hash);
if (pathPart === "") continue;
const oldRel = posix.normalize(posix.join(posix.dirname(move.from), pathPart));
const newRel = posix.normalize(posix.join(posix.dirname(move.to), pathPart));
if (oldRel.startsWith("..") || newRel.startsWith("..")) continue;
const stayed = existsSync(join(vault, oldRel));
const landed = existsSync(join(vault, newRel)) || (willLand?.(oldRel) ?? false);
if (stayed && !landed) {
const key = `${move.to}\u0000${raw}`;
if (!seen.has(key)) {
seen.add(key);
out.push({ note: move.to, target: raw });
}
}
}
}
return out.toSorted((a, b) =>
a.note === b.note ? (a.target < b.target ? -1 : 1) : a.note < b.note ? -1 : 1,
);
}
// ----- The operation ----------------------------------------------------------
/**
* Run one folder lifecycle operation. Ordering is load-bearing, as on the
* file surface: the envelope judges both folders before anything is read;
* the walk establishes the move set and the blast radius before the count
* guard runs; the occupancy pre-flight runs before the first rename; the
* rewrite runs once, over the successfully moved set's pairs; and the
* index evidence is read at the END, with the refresh claim trailing it.
*/
export async function folderLifecycle(
vault: string,
input: FolderLifecycleInput,
): Promise<FolderLifecycleResult> {
const apply = input.apply === true;
// Vault-identity write guard (context-integrity-gates, Unit J) - on the
// planning path too, exactly as the file surface asserts it: a plan
// names real vault paths, and computing one against a vault this
// process was not pointed at is already the confusion the guard exists
// to refuse.
// Through the vault adapter (design D14 items 8, 13): a vault is
// required, and the vault identity guard holds.
assertNoteVaultForWrite(vault, "the folder lifecycle");
if (!isFolderLifecycleAction(input.action)) {
throw new NoteLifecycleError(
"wrong_action",
`the folder lifecycle runs ${FOLDER_LIFECYCLE_ACTIONS.join(" | ")}; ` +
`'${input.action}' is a note-file action and refuses a folder subject`,
);
}
const action = input.action;
const source = resolveFolderTarget(vault, input.path);
// A folder that holds the view folder moves the view's pages with it.
const holdsView = viewFolderRefusal(vault, source.relPath, "the folder lifecycle", {
container: true,
});
if (holdsView !== null) throw new CreateNoteError("excluded", holdsView);
const sourceStat = statOrNull(source.abs);
if (sourceStat === null || !sourceStat.isDirectory()) {
throw new NoteLifecycleError("source_missing", `no note folder at ${source.relPath}`);
}
// The source is judged, moved and reported under its REAL spelling.
// Every judgment below compares or slices it against walk spellings
// and real locations, so an alias-spelled source would plan a move of
// names the disk does not answer to. The envelope has already vetted
// the real location - it refuses a path whose realpath leaves the
// vault or lands under `Brain/` - so this only makes the name honest.
const sourceRel = realSpelling(vault, source.relPath);
const sourceFolder =
sourceRel === source.relPath
? source
: { relPath: sourceRel, abs: ensureInsideVault(join(vault, sourceRel), vault) };
// Pass one: walk the whole vault once. This is the move set's source,
// the post-move population the minimal spellings are computed against,
// and the filesScanned denominator - one walk, so no two of those can
// see different vaults.
const walk = retargetWikilinks(vault, [], { root: VAULT_ROOT_REL, apply: false });
const vaultFiles = walk.files;
// The move set is the walked files whose REAL LOCATION is inside the
// source's real path, carried under that real spelling. The walk lists
// a file under whichever alias of its directory won the walk (it skips
// a directory whose realpath was already visited), so membership - and
// the spelling every move pair and rewrite pair carries - must be
// decided by where a file really lives: a symlinked directory inside
// the source puts ANOTHER folder's notes under the source's spelling,
// and an alias elsewhere puts the source's own notes under a foreign
// one. The walk dedupes directories by realpath, so each file is
// listed under exactly one spelling and the set cannot hold a file
// twice. (The realpath read is memoized per spelling; the judgment is
// order-independent, so either alias order plans the same move.)
const realCache = new Map<string, string>();
const realOf = (rel: string): string => {
const cached = realCache.get(rel);
if (cached !== undefined) return cached;
const real = realSpelling(vault, rel);
realCache.set(rel, real);
return real;
};
const movingReal = new Set<string>();
for (const rel of vaultFiles) {
const real = realOf(rel);
if (real === sourceRel || real.startsWith(`${sourceRel}/`)) movingReal.add(real);
}
const movingSet = [...movingReal].toSorted();
// The caller's reach judges the MOVE SET, and it judges BEFORE the
// destination is resolved: one note under the folder that the caller
// may not read refuses the WHOLE operation as a missing folder, on
// every later error path too - a denied folder that answers a
// destination mistake with `wrong_action` while a truly missing one
// answers `source_missing` would be an existence oracle. Skipping the
// denied files would still leak them - through the occupancy
// pre-flight, the rewrite pairs and the residue report - and moving
// them would relocate pages the caller cannot read, so the refusal
// reads exactly as the file surface's missing-note one. (A folder is
// not itself a page, so its notes are what the reach predicate can
// judge.)
if (movingSet.some((rel) => input.readable?.(rel) === false)) {
throw new NoteLifecycleError("source_missing", `no note folder at ${source.relPath}`);
}
const reported = (rel: string): boolean => input.readable?.(rel) ?? true;
const destination = resolveFolderDestination(vault, input, sourceFolder);
// A destination that IS the source's directory entry - the case-only
// folder rename on a host that folds case - cannot be performed by
// re-homing the folder's files: the entry keeps its spelling, the
// prune cannot remove it, and the receipt would name a move that
// never happened. Refused before anything is planned, on the plan
// too: a dry run that previews a move it cannot perform is a lie.
if (namesSameEntry(sourceFolder.abs, destination.abs)) {
throw new NoteLifecycleError(
"destination_unchanged",
`${action} destination ${destination.relPath} is the source folder's own directory ` +
"entry on this host (a case-only spelling); moving the folder's files cannot " +
"re-case the entry - rename the directory itself",
);
}
// An empty move set over a folder the disk says is non-empty is not a
// quiet success waiting to happen when the spelling is the fault: a
// path whose case (or Unicode normalization form) differs from the
// vault's real names stats fine on a case-insensitive host and yet
// matches no walked file, and the operation would report applied:true
// with an empty `moved` over notes that are really there. The same
// empty applied success is what a symlinked entry inside the source
// used to produce from the other direction: the walk holds spellings
// that fold under the path, but each names a file whose real location
// is elsewhere. Both shapes are recognisable and refused, naming the
// suspicion. A folder the walk has NOTHING under, whatever it holds on
// disk, is simply not a Markdown subject: an attachments-only or
// empty-subtree folder moves an empty set, keeps its contents, and the
// residue report says so - unless the disk holds Markdown under the
// source that NO walked spelling accounts for (out of the caller's
// vault scope, or a directory the walk could not read), which is the
// third shape of the same lie and refused too. A directory this
// process cannot read states nothing about emptiness either, so it
// does not refuse here - the per-file machinery names the fault if the
// move really is attempted.
const sourceEntries = readdirOrNull(sourceFolder.abs);
if (movingSet.length === 0 && sourceEntries !== null && sourceEntries.length > 0) {
const fold = (rel: string): string => `${rel.normalize("NFC").toLowerCase()}/`;
const foldedSource = fold(sourceRel);
if (vaultFiles.some((rel) => fold(rel).startsWith(foldedSource))) {
throw new NoteLifecycleError(
"move_set_empty",
`no Markdown moves from ${sourceRel} but the folder is not empty on disk: the walk saw ` +
`${vaultFiles.length} Markdown file(s) spelled under the path, and none of them ` +
"really lives inside it - each is reached through a symlink whose target the move " +
"does not follow, or sits under a different casing or character normalization of " +
"the path - check the folder's own names against the vault's",
);
}
if (subtreeHoldsMarkdown(vault, sourceRel)) {
throw new NoteLifecycleError(
"move_set_empty",
`no Markdown moves from ${sourceRel} but the folder is not empty on disk: it holds ` +
"Markdown that no walked spelling accounts for - excluded by vault scope, or a " +
"directory the walk could not read - and moving none of it is refused rather than " +
"reported as an empty success",
);
}
}
const planned: PlannedMove[] = movingSet.map((fromRel) => {
const toRel = `${destination.relPath}${fromRel.slice(sourceRel.length)}`;
const fromAbs = ensureInsideVault(join(vault, fromRel), vault);
const toAbs = ensureInsideVault(join(vault, toRel), vault);
return { fromRel, toRel, fromAbs, toAbs, sameEntry: namesSameEntry(fromAbs, toAbs) };
});
// The occupancy gate runs on the plan too: a dry run that reports a
// move it cannot perform would preview a lie.
assertDestinationsFree(planned, sourceFolder.abs, destination);
// The post-move population: every walked file that is not moving - by
// real location, so a foreign note that merely sat under the source's
// alias spelling stays in the population the minimal spellings are
// disambiguated against - plus every destination. The folder analogue
// of the file surface's postRelocationPopulation, derived from the
// same walked list.
const newRels = new Set(planned.map((move) => move.toRel));
const postPopulation = [
...vaultFiles.filter((rel) => !movingReal.has(realOf(rel))),
...newRels,
].toSorted();
// One pair set, no bare basename rung: a folder move never changes a
// basename, so the bare `[[Name]]` spellings keep resolving and
// bareNameRepairs has nothing to do. Each old spelling collapses onto
// the minimal spelling of the destination, as on the file surface.
const pairsFor = (moves: ReadonlyArray<PlannedMove>): { from: string; to: string }[] =>
moves.flatMap((move) => {
const to = minimalSpellingFor(move.toRel, postPopulation);
return [
{ from: move.fromRel, to },
{ from: withoutSuffix(move.fromRel), to },
];
});
const plannedPairs = pairsFor(planned);
const probe = retargetWikilinks(
vault,
plannedPairs.map((pair) => ({ from: pair.from })),
{ root: VAULT_ROOT_REL, apply: false },
);
const inboundFiles = probe.matched.filter(reported);
const filesScanned = vaultFiles.filter(reported).length;
assertExpectedCount({
matched: inboundFiles.length,
expect: input.expect ?? null,
strict: input.strict === true,
willMutate: apply,
matchList: inboundFiles,
});
let moved: FolderMovedPath[] = apply
? []
: // A plan-only run relocates nothing, so an empty `moved` would read
// as "nothing to do" - the plan IS the preview, and it reports the
// full set the apply would relocate (recon 1.3: a dry run reports
// the full planned set and writes nothing).
planned.map((move) => ({ from: move.fromRel, to: move.toRel }));
let moveFailures: FolderMoveFailure[] = [];
// Nothing has been left behind until something has been moved.
let leftBehind: ReadonlyArray<string> = [];
let rewritten: ReadonlyArray<string> = [];
let rewriteFailures: ReadonlyArray<{ readonly path: string; readonly reason: string }> = [];
let appliedPairs: ReadonlyArray<{ readonly from: string; readonly to: string }> = [];
if (apply) {
// The destination folder exists before the first relocation, so a
// zero-file move set still lands somewhere when the SOURCE folder
// was itself empty (the pre-flight has already approved or refused
// this exact path). A folder that KEEPS entries - the attachments-
// only case - creates nothing: its destination directory would hold
// no file and no folder, just residue this operation invented.
const destinationExisted = statOrNull(destination.abs) !== null;
// The deepest ancestor of the destination that is already on disk
// ("." when that is the vault root): the directories this apply
// invents all sit strictly below it, and the cleanup of an invented
// chain stops AT it - before removing anything. A directory that was
// already here is not this operation's to remove, empty or not.
let existingAncestor = ".";
if (!destinationExisted) {
let probe = dirname(destination.relPath);
while (probe !== ".") {
if (statOrNull(ensureInsideVault(join(vault, probe), vault)) !== null) {
existingAncestor = probe;
break;
}
const parentRel = dirname(probe);
if (parentRel === probe) break;
probe = parentRel;
}
}
if (planned.length > 0 || sourceEntries === null || sourceEntries.length === 0) {
mkdirSync(destination.abs, { recursive: true });
}
// The directories below the destination that are already on disk
// before the first relocation - a failed move's branch the vault
// already had, empty or not, is the vault's own and never this
// cleanup's to remove. Recorded now, before any of it can change.
const preExistingBranchDirs = new Set<string>();
for (const move of planned) {
let dir = dirname(move.toRel);
while (dir !== destination.relPath && dir !== ".") {
if (statOrNull(ensureInsideVault(join(vault, dir), vault)) !== null) {
preExistingBranchDirs.add(dir);
}
const parentRel = dirname(dir);
if (parentRel === dir) break;
dir = parentRel;
}
}
// The destination spellings the per-file machinery created for moves
// that then failed: the invented subtree the cleanup below offers
// back to the filesystem.
const failedDestinations: string[] = [];
// The moves run in sorted order and the set continues past a failure:
// by the time one file cannot relocate, others already have, and
// undoing them would unlink destination names - new destructive
// behavior no gate covers. The report names the split instead.
for (const move of planned) {
try {
(input.relocate ?? relocateFileBytes)(move.fromAbs, move.toAbs, move.toRel, move.sameEntry);
moved.push({ from: move.fromRel, to: move.toRel });
} catch (err) {
let reason = err instanceof Error ? err.message : String(err);
failedDestinations.push(move.toRel);
// A fault AFTER the destination name was created - a linked name
// (same inode) or a cross-device copy the fallback wrote - leaves
// bytes at `toRel` while the report is about to say this path
// "never moved". The source name still holds the original bytes
// whenever it exists, so the extra destination name is dropped
// before the failure is reported; if even that fails, the
// failure says so. The name is judged with LSTAT, not
// `existsSync`: a name that dangles - a link whose target the
// new depth cannot see - is still a name this call created, and
// following the link would see nothing and leave it standing.
// A source that no longer exists means the unlink SUCCEEDED and
// a later step threw - the file moved, and the destination name
// is the only copy, so it stays. And a destination this call
// never created is never this operation's to drop: the
// pre-flight cleared the name, so `destination_occupied` means a
// foreign file appeared there between the check and the link,
// and unlinking it would delete bytes this operation did not
// write.
const occupied = err instanceof NoteLifecycleError && err.code === "destination_occupied";
if (!move.sameEntry && !occupied && lstatOrNull(move.toAbs) !== null) {
if (existsSync(move.fromAbs)) {
try {
unlinkSync(move.toAbs);
} catch (cleanup) {
reason +=
`; the destination name ${move.toRel} was written before the fault and ` +
`could not be dropped either (${cleanup instanceof Error ? cleanup.message : String(cleanup)})`;
}
} else {
reason += `; the destination name ${move.toRel} holds the moved bytes`;
}
}
moveFailures.push({ path: move.fromRel, reason });
}
}
// The directories the per-file machinery invented for FAILED moves
// never stay behind: each failed move's own destination spelling
// names its branch, offered to rmdirSync deepest-first, each only
// while genuinely empty - so a moved file's branch, a foreign name or
// a name that could not be dropped keeps its branch standing - and a
// branch that was already here is spared by name. When NOTHING moved,
// the destination folder and the chain the recursive mkdir invented
// above it go too, up to - never including - the ancestor that was
// already here; with a partial set they hold real moves, so the walk
// stops at the destination folder. A destination that existed before,
// or one an empty-source move deliberately created, is not this
// cleanup's business.
if (failedDestinations.length > 0) {
const doomed = new Set<string>();
if (moved.length === 0 && !destinationExisted) {
doomed.add(destination.relPath);
let up = dirname(destination.relPath);
while (up !== "." && up !== existingAncestor) {
doomed.add(up);
const parentRel = dirname(up);
if (parentRel === up) break;
up = parentRel;
}
}
for (const toRel of failedDestinations) {
let dir = dirname(toRel);
while (dir !== destination.relPath && dir !== ".") {
doomed.add(dir);
const parentRel = dirname(dir);
if (parentRel === dir) break;
dir = parentRel;
}
}
const deepestFirst = [...doomed]
.filter((rel) => !preExistingBranchDirs.has(rel))
.toSorted((a, b) => b.length - a.length);
for (const rel of deepestFirst) {
try {
rmdirSync(ensureInsideVault(join(vault, rel), vault));
} catch {
// Not empty (a foreign name, or a name that could not be
// dropped) or not removable: what stands, stands, and the
// report already names where every file is.
}
}
}
// The folders the moves emptied go with their files: every ancestor
// of a successfully moved file, up to and including the subject, is
// offered to rmdirSync deepest-first, and only genuinely empty ones
// go - so a failed file's parent stays exactly where the report says
// its bytes are, and directories the move never touched (empty
// siblings, a subtree that held no Markdown) are not this operation's
// to delete.
pruneEmptiedFolders(vault, sourceRel, moved);
// An EMPTY folder's move is the directory entry itself: nothing was
// relocated, so the prune has no moved file whose ancestors name the
// subject, and the entry is dropped by hand - but only while the disk
// still says the source is empty, and never when the source keeps
// entries it was never going to move (the attachments-only case).
if (planned.length === 0 && (readdirOrNull(sourceFolder.abs) ?? []).length === 0) {
try {
rmdirSync(sourceFolder.abs);
} catch {
// The entry is not removable (or re-appeared between the read and
// the removal): the residue report names what stayed.
}
}
// Whatever the prune could not remove is exactly what stayed - a
// non-Markdown file beside the notes, a symlinked entry whose real
// location is outside the source, or a failed file's folder - and
// the report names it rather than reading as if the source folder
// went with its notes.
leftBehind = (readdirOrNull(sourceFolder.abs) ?? []).toSorted();
// ONE rewrite pass over the SUCCESSFULLY moved set's pairs, under the
// destination. A failed file's pairs are excluded, which is the
// correct outcome: its inbound links still resolve to where its
// bytes actually are.
const movedPlanned = planned.filter((move) =>
moved.some((entry) => entry.from === move.fromRel),
);
appliedPairs = pairsFor(movedPlanned);
const pass = retargetWikilinks(vault, appliedPairs, {
root: VAULT_ROOT_REL,
apply: true,
neverRewrite: APPEND_ONLY_REL,
});
rewritten = pass.rewritten.filter(reported);
rewriteFailures = pass.failed
.filter((failure) => reported(failure.path))
.map((failure) => ({ path: failure.path, reason: failure.reason }))
.toSorted((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
}
// The MOVE destroys nothing; the REWRITE overwrites hand-authored prose
// in place, so the blast radius is declared from the files this call
// actually rewrote - the file surface's reading, region for region.
const recoverability = classifyRecoverability({
recoveryPoint: false,
blastRadius: {
...(rewritten.some((rel) => pathCovers(BRAIN_ROOT_REL, rel)) ? { brainTopLevel: true } : {}),
...(rewritten.some((rel) => !pathCovers(BRAIN_ROOT_REL, rel))
? { outsideBrainRoot: true }
: {}),
},
});
const index: IndexEvidence = await readIndexEvidence(vault, apply, input.refreshConfigPath);
// The refresh claim trails the evidence read on purpose: the evidence
// must describe the index as this call left it, and the claim starts a
// DETACHED run that will not have landed by any instant this call can
// observe. A plan-only run claims nothing and refused nothing.
let refresh: IndexRefresh;
let refreshReason: string | null;
if (apply) {
const claim = await claimPostWriteRefresh(
vault,
index,
input.refreshSpawn,
input.now,
input.refreshConfigPath,
);
refresh = claim.refresh;
refreshReason = claim.refreshReason;
} else {
refresh = INDEX_REFRESH.notClaimed;
refreshReason = null;
}
// The relative-link judgment (M17) reads the moved notes' bytes once,
// from where they now are: the planned set on a plan (the notes have
// not moved - the plan is the preview), the SUCCESSFULLY moved set on
// an apply - a failed file never moved, so its relative links still
// resolve and name no fault.
const linkMoves = (
apply
? moved.map((m) => ({
from: m.from,
to: m.to,
bytesAbs: ensureInsideVault(join(vault, m.to), vault),
}))
: planned.map((m) => ({ from: m.fromRel, to: m.toRel, bytesAbs: m.fromAbs }))
).toSorted((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : 0));
const dangling = danglingRelativeLinks(
vault,
linkMoves,
apply
? undefined
: // The plan's promise: a target whose real location is inside the
// source's real path is IN the move set and will be at the new
// location once the move runs.
(oldRel: string) => movingReal.has(realSpelling(vault, oldRel)),
);
return Object.freeze({
action,
from: sourceRel,
to: destination.relPath,
applied: apply,
moved: Object.freeze(
moved.toSorted((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : 0)),
),
moveFailures: Object.freeze(
moveFailures.toSorted((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
),
leftBehind: Object.freeze([...leftBehind]),
danglingRelativeLinks: Object.freeze(dangling),
recoverability,
snapshot: null,
references: Object.freeze({
filesScanned,
inboundFiles: Object.freeze([...inboundFiles]),
filesRewritten: rewritten.length,
rewrittenSpellings: Object.freeze([...(apply ? appliedPairs : plannedPairs)]),
rewriteFailures: Object.freeze([...rewriteFailures]),
basename: BASENAME_REWRITE.notNeeded,
index,
refresh,
refreshReason,
}),
});
}
/**
* Remove the directories the moves genuinely emptied, deepest first.
* `rmdirSync` removes only an empty directory, so a folder whose subtree
* still holds a failed file - or any file this surface does not address -
* keeps it, which is exactly where the report says the bytes are. The
* candidate set is derived from the MOVED FILES' ancestor chains up to
* the subject - never from a walk of the subject's subtree - so a
* symlinked directory anywhere under the source is neither followed nor
* removed, and directories the move never touched (empty siblings, a
* no-Markdown subtree) are not this operation's to delete. The folders
* ABOVE the subject are not its business either, and an emptied
* `Projects/` left behind reads as the ordinary residue a file move
* leaves too.
*/
function pruneEmptiedFolders(
vault: string,
fromRel: string,
moved: ReadonlyArray<FolderMovedPath>,
): void {
const candidates = new Set<string>();
for (const file of moved) {
let dir = dirname(file.from);
// Walk the ancestor chain in VAULT-RELATIVE spellings - the move
// report's own paths, never names resolved through the filesystem -
// and stop at the subject itself. The walk is bounded to fail closed:
// a moved path outside the subject (a different spelling, a future
// caller) can never send the walk below the vault root, where
// `dirname` stops changing and the loop would never end.
candidates.add(dir);
while (dir !== fromRel) {
const parent = dirname(dir);
if (parent === dir || parent === ".") break;
dir = parent;
candidates.add(dir);
}
}
const deepestFirst = [...candidates]
.filter((rel) => rel === fromRel || rel.startsWith(`${fromRel}/`))
.toSorted((a, b) => b.length - a.length);
for (const rel of deepestFirst) {
try {
rmdirSync(ensureInsideVault(join(vault, rel), vault));
} catch {
// The directory is not empty (or not removable): the residue
// stands, and the report already names where every file is.
}
}
}