pi-obsidian-memory 0.0.1 → 0.1.0

package/src/services/vault/publish.ts

@@ -0,0 +1,52 @@
+import { type Note, renderNote } from "#src/domain"
+import { createDirectory, findFileIgnoringCase, hashOf, publishExclusively } from "#src/services/vault/filesystem"
+import { noteFileName } from "./paths.ts"
+import { refuseExisting, refuseWrite } from "./refusals.ts"
+import { resolveFile, resolveFolder } from "./resolve.ts"
+import type { CreateResult } from "./types.ts"
+
+export async function writeValidatedNote(vault: string, folder: string, note: Note): Promise<CreateResult> {
+  const directory = await resolveFolder(vault, folder)
+  if (!directory.succeeded) {
+    return directory
+  }
+
+  const path = await resolveFile(vault, folder, noteFileName(note.statement))
+  if (!path.succeeded) {
+    return path
+  }
+
+  const made = await createDirectory(directory.output)
+  if (!made.succeeded) {
+    return refuseWrite(folder, note.statement, made)
+  }
+
+  const existing = await findFileIgnoringCase(directory.output, noteFileName(note.statement))
+  if (existing.succeeded) {
+    return refuseExisting(folder, existing.output)
+  }
+  if (existing.reason !== "not-found") {
+    return existing
+  }
+
+  const text = renderNote(note)
+  const written = await publishExclusively(path.output, text)
+  if (!written.succeeded) {
+    if (written.reason === "exists") {
+      const occupied = await findFileIgnoringCase(directory.output, noteFileName(note.statement))
+      if (!occupied.succeeded) {
+        return occupied
+      }
+
+      const refused = refuseExisting(folder, occupied.output)
+      return { ...refused, problems: [...refused.problems, ...written.problems.slice(1)] }
+    }
+    return refuseWrite(folder, note.statement, written)
+  }
+
+  const result: CreateResult = { succeeded: true, output: { note, hash: hashOf(text) } }
+  if (written.maintenanceProblems) {
+    result.maintenanceProblems = written.maintenanceProblems
+  }
+  return result
+}

package/src/services/vault/read.ts

@@ -0,0 +1,46 @@
+import { parseNote, validateNote } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { hashOf, readRawFile } from "#src/services/vault/filesystem"
+import { displayNotePath } from "./display.ts"
+import { noteFileName } from "./paths.ts"
+import { resolveFile } from "./resolve.ts"
+import type { ReadNoteResult } from "./types.ts"
+
+export async function readNote(vault: VaultContext, folder: string, statement: string): Promise<ReadNoteResult> {
+  const path = await resolveFile(vault.path, folder, noteFileName(statement))
+  if (!path.succeeded) {
+    return path
+  }
+
+  return readResolvedNote(vault, folder, statement, path.output)
+}
+
+export async function readResolvedNote(
+  vault: VaultContext,
+  folder: string,
+  statement: string,
+  path: string,
+): Promise<ReadNoteResult> {
+  const file = await readRawFile(path)
+  if (!file.succeeded) {
+    if (file.reason !== "not-found") {
+      return file
+    }
+
+    const problem = `${displayNotePath(folder, statement)} does not exist`
+    return { succeeded: false, reason: "not-found", problems: [problem] }
+  }
+
+  const parsed = parseNote(statement, file.output.toString("utf8"))
+  if (!parsed.succeeded) {
+    return { succeeded: false, reason: "invalid", problems: parsed.problems }
+  }
+
+  const hash = hashOf(file.output)
+  const validated = validateNote(parsed.output, vault.limits)
+  if (!validated.succeeded) {
+    return { succeeded: false, reason: "needs-fixing", problems: validated.problems, parsed: parsed.output, hash }
+  }
+
+  return { succeeded: true, output: { note: validated.output, hash } }
+}

package/src/services/vault/refresh-folders.ts

@@ -0,0 +1,197 @@
+import { basename, dirname, relative, sep } from "node:path"
+
+import { renderFolderIndex } from "#src/domain"
+import { catalogStat } from "#src/services/vault/catalog"
+import type { NamedVaultContext } from "#src/services/vault/context"
+import { linkStatOf, readRawFile, realPathOf, type WriteResult, writeAtomically } from "#src/services/vault/filesystem"
+import { FOLDER_INDEX_FILE_NAME } from "./constants.ts"
+import { contentsOf } from "./folder-contents.ts"
+import { listSettledFolder } from "./list.ts"
+import { maintenanceFailure, planRefreshFolders } from "./refresh-plan.ts"
+import { refuseWrite } from "./refusals.ts"
+import { resolveFile, resolveFolder } from "./resolve.ts"
+import type {
+  FolderRefreshed,
+  FolderRefreshOutcome,
+  FolderRefreshResult,
+  RefreshContinuation,
+  RefreshedFolder,
+  RefreshRefusal,
+  RefreshResult,
+  RefreshScope,
+} from "./types.ts"
+
+export async function refreshFolders(
+  context: NamedVaultContext,
+  folders: string[],
+  shouldContinue: RefreshContinuation,
+  scope: RefreshScope,
+): Promise<FolderRefreshResult> {
+  const planned = await planRefreshFolders(context.path, folders, scope)
+  if (!planned.succeeded) {
+    return { ...planned, refreshed: [] }
+  }
+
+  const failures: RefreshRefusal[] = [...planned.output.refusals]
+  const maintenanceProblems: string[] = []
+  const refreshed: RefreshedFolder[] = []
+  const writtenPaths = new Map<string, FolderRefreshed>()
+  for (const folder of planned.output.folders) {
+    if (!shouldContinue()) {
+      failures.unshift(interruption())
+      break
+    }
+
+    const written = await refreshFolder(context, folder, writtenPaths, shouldContinue)
+    if (!written.succeeded && written.reason === "interrupted") {
+      failures.unshift(written)
+      break
+    }
+    if (!written.succeeded) {
+      failures.push(written)
+      continue
+    }
+
+    refreshed.push({ folder, index: written.output.index, settled: written.output.settled })
+    if (written.output.maintenanceProblems) {
+      maintenanceProblems.push(...written.output.maintenanceProblems)
+    }
+  }
+
+  return { ...summarize(failures, maintenanceProblems), refreshed }
+}
+
+function interruption(): RefreshRefusal {
+  return {
+    succeeded: false,
+    reason: "interrupted",
+    problems: ["Folder index maintenance stopped before every index was refreshed"],
+  }
+}
+
+export function alwaysContinue(): boolean {
+  return true
+}
+
+function summarize(failures: RefreshRefusal[], maintenanceProblems: string[]): RefreshResult {
+  const [first] = failures
+  if (first) {
+    return {
+      succeeded: false,
+      reason: first.reason,
+      problems: [...new Set([...failures.flatMap((failure) => failure.problems), ...maintenanceProblems])],
+    }
+  }
+  if (maintenanceProblems.length > 0) {
+    return { succeeded: true, maintenanceProblems }
+  }
+  return { succeeded: true }
+}
+
+async function refreshFolder(
+  context: NamedVaultContext,
+  folder: string,
+  writtenPaths: Map<string, FolderRefreshed>,
+  shouldContinue: RefreshContinuation,
+): Promise<FolderRefreshOutcome> {
+  try {
+    return await writeIndex(context, folder, writtenPaths, shouldContinue)
+  } catch (error) {
+    if (!(error instanceof Error)) {
+      throw error
+    }
+
+    return maintenanceFailure(error)
+  }
+}
+
+async function writeIndex(
+  context: NamedVaultContext,
+  folder: string,
+  writtenPaths: Map<string, FolderRefreshed>,
+  shouldContinue: RefreshContinuation,
+): Promise<FolderRefreshOutcome> {
+  const directory = await resolveFolder(context.path, folder)
+  if (!directory.succeeded) {
+    return directory
+  }
+
+  const path = await resolveFile(context.path, folder, FOLDER_INDEX_FILE_NAME)
+  if (!path.succeeded) {
+    return path
+  }
+  if (!(await isOwnIndex(directory.output, path.output))) {
+    return {
+      succeeded: false,
+      reason: "invalid",
+      problems: [`Folder index of "${folder}" must be the index.md of its own folder`],
+    }
+  }
+  const alreadyWritten = writtenPaths.get(path.output)
+  if (alreadyWritten) {
+    return { succeeded: true, output: { index: alreadyWritten.index, settled: alreadyWritten.settled } }
+  }
+
+  const root = await resolveFolder(context.path, "")
+  if (!root.succeeded) {
+    return root
+  }
+
+  const physical = relative(root.output, directory.output).split(sep).join("/")
+  const listing = await listSettledFolder(context, physical)
+  if (!listing.succeeded) {
+    return listing
+  }
+
+  const contents = await contentsOf(context, physical, listing.output.listing)
+  if (!shouldContinue()) {
+    return interruption()
+  }
+
+  const refreshed = await writeAndStat(path.output, folder, renderFolderIndex(contents), listing.output.settled)
+  if (refreshed.succeeded) {
+    writtenPaths.set(path.output, refreshed.output)
+  }
+  return refreshed
+}
+
+async function writeAndStat(
+  path: string,
+  folder: string,
+  text: string,
+  settled: boolean,
+): Promise<FolderRefreshOutcome> {
+  const written = await writeChangedIndex(path, text)
+  if (!written.succeeded) {
+    return refuseWrite(folder, "index", written)
+  }
+
+  const index = await linkStatOf(path)
+  if (!index.succeeded) {
+    return index
+  }
+
+  const refreshed: FolderRefreshed = { index: catalogStat(index.output), settled }
+  if (written.maintenanceProblems) {
+    refreshed.maintenanceProblems = written.maintenanceProblems
+  }
+  return { succeeded: true, output: refreshed }
+}
+
+async function isOwnIndex(directory: string, target: string): Promise<boolean> {
+  if (basename(target).toLowerCase() !== FOLDER_INDEX_FILE_NAME) {
+    return false
+  }
+  if (dirname(target) === directory) {
+    return true
+  }
+
+  const [home, targetHome] = await Promise.all([realPathOf(directory), realPathOf(dirname(target))])
+  return home.succeeded && targetHome.succeeded && home.output === targetHome.output
+}
+
+async function writeChangedIndex(path: string, text: string): Promise<WriteResult> {
+  const existing = await readRawFile(path)
+  if (existing.succeeded && existing.output.equals(Buffer.from(text))) return { succeeded: true }
+  return writeAtomically(path, text)
+}

package/src/services/vault/refresh-plan.ts

@@ -0,0 +1,79 @@
+import { relative, sep } from "node:path"
+
+import { ancestorFolders } from "#src/domain"
+import { linkStatOf } from "#src/services/vault/filesystem"
+import type { Succeeded } from "#src/shared"
+import { resolveFolder } from "./resolve.ts"
+import type { RefreshPlan, RefreshRefusal, RefreshScope, ResolveRefusal } from "./types.ts"
+
+export async function planRefreshFolders(
+  vault: string,
+  folders: string[],
+  scope: RefreshScope,
+): Promise<Succeeded<RefreshPlan> | RefreshRefusal> {
+  try {
+    return await planFolders(vault, folders, scope)
+  } catch (error) {
+    if (!(error instanceof Error)) {
+      throw error
+    }
+
+    return maintenanceFailure(error)
+  }
+}
+
+async function planFolders(
+  vault: string,
+  folders: string[],
+  scope: RefreshScope,
+): Promise<Succeeded<RefreshPlan> | ResolveRefusal> {
+  const root = await resolveFolder(vault, "")
+  if (!root.succeeded) {
+    return root
+  }
+
+  const discoveredFolders = new Set(folders)
+  const ancestors = new Set<string>()
+  const refusals: RefreshRefusal[] = []
+  for (const folder of discoveredFolders) {
+    const checked = await resolveFolder(vault, folder)
+    if (!checked.succeeded) {
+      refusals.push(checked)
+      continue
+    }
+
+    const existing = await linkStatOf(checked.output)
+    if (!existing.succeeded) {
+      refusals.push(existing)
+      continue
+    }
+
+    const physical = relative(root.output, checked.output).split(sep).join("/")
+    let selected = [folder]
+    if (scope === "with-ancestors") {
+      selected = [...ancestorFolders(physical), ...ancestorFolders(folder)]
+    }
+    for (const chosen of selected) {
+      ancestors.add(chosen)
+      discoveredFolders.add(chosen)
+    }
+  }
+
+  return { succeeded: true, output: { folders: ancestors, refusals } }
+}
+
+export function maintenanceFailure(error: Error): RefreshRefusal {
+  if (
+    !("code" in error) ||
+    typeof error.code !== "string" ||
+    !("syscall" in error) ||
+    typeof error.syscall !== "string" ||
+    !("errno" in error) ||
+    typeof error.errno !== "number" ||
+    !Number.isFinite(error.errno)
+  ) {
+    throw error
+  }
+
+  return { succeeded: false, reason: "io-error", problems: [error.message] }
+}

package/src/services/vault/refresh.ts

@@ -0,0 +1,8 @@
+import type { NamedVaultContext } from "#src/services/vault/context"
+import { alwaysContinue, refreshFolders } from "./refresh-folders.ts"
+import type { RefreshResult } from "./types.ts"
+
+export async function refreshIndexes(vault: NamedVaultContext, folder: string): Promise<RefreshResult> {
+  const { refreshed: _refreshed, ...result } = await refreshFolders(vault, [folder], alwaysContinue, "with-ancestors")
+  return result
+}

package/src/services/vault/refusals.ts

@@ -0,0 +1,23 @@
+import type { WriteFailure } from "#src/services/vault/filesystem"
+import { NOTE_EXTENSION } from "./constants.ts"
+import { displayNotePath } from "./display.ts"
+import type { CreateRefusal, ExistingNoteRefusal } from "./types.ts"
+
+export function refuseWrite(folder: string, statement: string, failure: WriteFailure): CreateRefusal {
+  const problem = `${displayNotePath(folder, statement)} cannot be written (${failure.code})`
+  if (failure.reason === "exists") {
+    return { succeeded: false, reason: "not-directory", problems: [problem, ...failure.problems.slice(1)] }
+  }
+
+  return { succeeded: false, reason: failure.reason, problems: [problem, ...failure.problems.slice(1)] }
+}
+
+export function refuseExisting(folder: string, fileName: string): ExistingNoteRefusal {
+  const existingStatement = fileName.slice(0, -NOTE_EXTENSION.length)
+  return {
+    succeeded: false,
+    reason: "exists",
+    existingStatement,
+    problems: [`${displayNotePath(folder, existingStatement)} already exists`],
+  }
+}

package/src/services/vault/relocate.ts

@@ -0,0 +1,131 @@
+import { dirname, relative, sep } from "node:path"
+
+import type { NamedVaultContext } from "#src/services/vault/context"
+import { linkStatOf } from "#src/services/vault/filesystem"
+import { writeValidatedNote } from "./publish.ts"
+import { alwaysContinue, refreshFolders } from "./refresh-folders.ts"
+import { checkRelocation, removeOriginal } from "./relocation-checks.ts"
+import { resolveFolder } from "./resolve.ts"
+import { resolveOriginalFile } from "./resolve-stored-file.ts"
+import type {
+  FileRelocationRequest,
+  PartialRelocation,
+  RelocationProgress,
+  RelocationResult,
+  RelocationWriteResult,
+} from "./types.ts"
+
+export async function relocateNote(
+  vault: NamedVaultContext,
+  request: FileRelocationRequest,
+): Promise<RelocationResult> {
+  const checked = await checkRelocation(vault, request)
+  if (!checked.succeeded) {
+    return checked
+  }
+
+  const root = await resolveFolder(vault.path, "")
+  if (!root.succeeded) {
+    return root
+  }
+
+  const progress: RelocationProgress = { written: [], maintenanceProblems: [] }
+  let moved: RelocationWriteResult
+  try {
+    moved = await writeAndRemove(vault.path, request, progress)
+    if (!moved.succeeded) {
+      return moved
+    }
+  } catch (error) {
+    if (progress.written.length === 0) {
+      throw error
+    }
+
+    let problem = "Lifecycle I/O failed after publishing notes"
+    if (error instanceof Error) {
+      problem = error.message
+    }
+
+    return partialOutcome(vault.path, request, progress, { succeeded: false, reason: "io-error", problems: [problem] })
+  }
+
+  const removedFolder = relative(root.output, dirname(moved.output)).split(sep).join("/")
+  const folders = [removedFolder, request.original.folder, ...request.written.map((placed) => placed.folder)]
+  const refreshed = await refreshFolders(vault, folders, alwaysContinue, "with-ancestors")
+  if (!refreshed.succeeded) {
+    progress.maintenanceProblems.push(...refreshed.problems)
+  } else if (refreshed.maintenanceProblems) {
+    progress.maintenanceProblems.push(...refreshed.maintenanceProblems)
+  }
+
+  if (progress.maintenanceProblems.length > 0) {
+    return { succeeded: true, maintenanceProblems: progress.maintenanceProblems }
+  }
+  return { succeeded: true }
+}
+
+async function writeAndRemove(
+  vault: string,
+  request: FileRelocationRequest,
+  progress: RelocationProgress,
+): Promise<RelocationWriteResult> {
+  for (const placed of request.written) {
+    const created = await writeValidatedNote(vault, placed.folder, placed.note)
+    if (!created.succeeded) {
+      if (progress.written.length === 0) {
+        return created
+      }
+      return partialOutcome(vault, request, progress, created)
+    }
+
+    progress.written.push(placed)
+    if (created.maintenanceProblems) {
+      progress.maintenanceProblems.push(...created.maintenanceProblems)
+    }
+  }
+
+  const removed = await removeOriginal(vault, request)
+  if (!removed.succeeded) {
+    return partialOutcome(vault, request, progress, removed)
+  }
+  return removed
+}
+
+async function partialOutcome(
+  vault: string,
+  request: FileRelocationRequest,
+  progress: RelocationProgress,
+  cause: PartialRelocation["cause"],
+): Promise<PartialRelocation> {
+  return {
+    succeeded: false,
+    reason: "partial",
+    cause,
+    problems: [...cause.problems, ...progress.maintenanceProblems],
+    written: progress.written,
+    originalState: await originalState(vault, request),
+  }
+}
+
+async function originalState(
+  vault: string,
+  request: FileRelocationRequest,
+): Promise<PartialRelocation["originalState"]> {
+  try {
+    const path = await resolveOriginalFile(vault, request)
+    if (!path.succeeded) {
+      return "unknown"
+    }
+
+    const stat = await linkStatOf(path.output)
+    if (stat.succeeded) {
+      return "present"
+    }
+    if (stat.reason === "not-found") {
+      return "missing"
+    }
+    return "unknown"
+  } catch {
+    return "unknown"
+  }
+}

package/src/services/vault/relocation-checks.ts

@@ -0,0 +1,89 @@
+import { checkNote, isRootArchive, type PlacedNote } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { findFileIgnoringCase, hashOf, readRawFile, removeFile } from "#src/services/vault/filesystem"
+import { displayNotePath } from "./display.ts"
+import { noteFileName } from "./paths.ts"
+import { refuseExisting, refuseWrite } from "./refusals.ts"
+import { resolveFolder } from "./resolve.ts"
+import { resolveOriginalFile } from "./resolve-stored-file.ts"
+import type { CheckResult, FileRelocationRequest, RemovalResult } from "./types.ts"
+
+export async function checkRelocation(vault: VaultContext, request: FileRelocationRequest): Promise<CheckResult> {
+  const unchanged = await checkUnchanged(vault.path, request)
+  if (!unchanged.succeeded) {
+    return unchanged
+  }
+
+  for (const placed of request.written) {
+    const problems = checkPlaced(placed, vault)
+    if (problems.length > 0) {
+      return { succeeded: false, reason: "invalid", problems }
+    }
+
+    const free = await checkFree(vault.path, placed)
+    if (!free.succeeded) {
+      return free
+    }
+  }
+  return { succeeded: true }
+}
+
+function checkPlaced(placed: PlacedNote, vault: VaultContext): string[] {
+  if (isRootArchive(placed.folder)) return []
+  return checkNote(placed.note, vault.limits)
+}
+
+async function checkUnchanged(vault: string, request: FileRelocationRequest): Promise<CheckResult> {
+  const path = await resolveOriginalFile(vault, request)
+  if (!path.succeeded) {
+    return path
+  }
+  return checkHash(path.output, request.original, request.hashWhenRead)
+}
+
+async function checkHash(path: string, placed: PlacedNote, hashWhenRead: string): Promise<CheckResult> {
+  const current = await readRawFile(path)
+  if (!current.succeeded && current.reason !== "not-found") {
+    return current
+  }
+  if (!current.succeeded || hashOf(current.output) !== hashWhenRead) {
+    const problem = `${displayNotePath(placed.folder, placed.note.statement)} changed on disk since it was read`
+    return { succeeded: false, reason: "conflict", problems: [problem] }
+  }
+  return { succeeded: true }
+}
+
+async function checkFree(vault: string, placed: PlacedNote): Promise<CheckResult> {
+  const directory = await resolveFolder(vault, placed.folder)
+  if (!directory.succeeded) {
+    return directory
+  }
+
+  const existing = await findFileIgnoringCase(directory.output, noteFileName(placed.note.statement))
+  if (existing.succeeded) {
+    return refuseExisting(placed.folder, existing.output)
+  }
+  if (existing.reason !== "not-found") {
+    return existing
+  }
+  return { succeeded: true }
+}
+
+export async function removeOriginal(vault: string, request: FileRelocationRequest): Promise<RemovalResult> {
+  const { original, hashWhenRead } = request
+  const path = await resolveOriginalFile(vault, request)
+  if (!path.succeeded) {
+    return path
+  }
+
+  const unchanged = await checkHash(path.output, original, hashWhenRead)
+  if (!unchanged.succeeded) {
+    return unchanged
+  }
+
+  const removed = await removeFile(path.output)
+  if (!removed.succeeded) {
+    return refuseWrite(original.folder, original.note.statement, removed)
+  }
+  return { succeeded: true, output: path.output }
+}

package/src/services/vault/resolve-stored-file.ts

@@ -0,0 +1,43 @@
+import { basename } from "node:path"
+
+import { checkVaultPath } from "#src/domain"
+import { realPathOf } from "#src/services/vault/filesystem"
+import { noteFileName, storedFilePath } from "./paths.ts"
+import { resolveFile } from "./resolve.ts"
+import type { FileRelocationRequest, ResolveResult } from "./types.ts"
+
+export async function resolveStoredFile(vault: string, path: string, statement: string): Promise<ResolveResult> {
+  const { folder, fileName } = storedFilePath(path)
+  const problems = [...checkVaultPath(path), ...checkStoredFileName(fileName, statement)]
+  if (problems.length > 0) return { succeeded: false, reason: "invalid", problems }
+
+  const resolved = await resolveFile(vault, folder, fileName)
+  if (!resolved.succeeded) return resolved
+  const canonical = await realPathOf(resolved.output)
+  if (!canonical.succeeded) {
+    if (canonical.reason === "not-found") return resolved
+    return canonical
+  }
+
+  const targetProblems = checkStoredFileName(basename(canonical.output), statement)
+  if (targetProblems.length > 0) return { succeeded: false, reason: "invalid", problems: targetProblems }
+  return canonical
+}
+
+export async function resolveOriginalFile(vault: string, request: FileRelocationRequest): Promise<ResolveResult> {
+  const { original, originalPath } = request
+  if (typeof originalPath !== "string") {
+    return resolveFile(vault, original.folder, noteFileName(original.note.statement))
+  }
+  if (storedFilePath(originalPath).folder !== original.folder) {
+    return { succeeded: false, reason: "invalid", problems: ["The original path must match the note folder"] }
+  }
+  return resolveStoredFile(vault, originalPath, original.note.statement)
+}
+
+function checkStoredFileName(fileName: string, statement: string): string[] {
+  if (fileName.slice(-3).toLowerCase() !== ".md" || fileName.slice(0, -3) !== statement) {
+    return ["The stored filename must match the note statement and have a Markdown extension"]
+  }
+  return []
+}