pi-obsidian-memory 0.0.1 → 0.1.0

package/src/services/vault/domain-rules.ts

@@ -0,0 +1,10 @@
+export {
+  diagnoseVault,
+  exportEntries,
+  type Note,
+  type NoteChange,
+  type PlacedNote,
+  updatedNote,
+  type VaultDiagnosis,
+  type VaultExportEntry,
+} from "#src/domain"

package/src/services/vault/draft.ts

@@ -0,0 +1,2 @@
+export type { MemoryDraft } from "#src/domain"
+export { MemoryDraftSchema, newNote } from "#src/domain"

package/src/services/vault/filesystem/failures.ts

@@ -0,0 +1,53 @@
+import type { ReadFailure, WriteFailure } from "./types.ts"
+
+export function readFailure(error: Error, path: string): ReadFailure {
+  const code = errorCode(error)
+  const problems = [`${path} cannot be read (${code})`]
+  switch (code) {
+    case "ENOENT":
+      return { succeeded: false, reason: "not-found", code, problems }
+    case "ENOTDIR":
+    case "EISDIR":
+      return { succeeded: false, reason: "not-directory", code, problems }
+    case "EACCES":
+    case "EPERM":
+    case "EBUSY":
+    case "ELOOP":
+      return { succeeded: false, reason: "not-readable", code, problems }
+    default:
+      throw error
+  }
+}
+
+export function writeFailure(error: Error, path: string): WriteFailure {
+  const code = errorCode(error)
+  const problems = [`${path} cannot be written (${code})`]
+  switch (code) {
+    case "ENOENT":
+      return { succeeded: false, reason: "not-found", code, problems }
+    case "ENOTDIR":
+    case "EISDIR":
+      return { succeeded: false, reason: "not-directory", code, problems }
+    case "EEXIST":
+      return { succeeded: false, reason: "exists", code, problems }
+    case "EACCES":
+    case "EPERM":
+    case "EBUSY":
+    case "ENOSPC":
+    case "EDQUOT":
+    case "EROFS":
+    case "ENOTSUP":
+    case "EXDEV":
+    case "EMLINK":
+      return { succeeded: false, reason: "not-writable", code, problems }
+    default:
+      throw error
+  }
+}
+
+export function errorCode(error: Error): string {
+  if ("code" in error && typeof error.code === "string") {
+    return error.code
+  }
+  return error.name
+}

package/src/services/vault/filesystem/hash.ts

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto"
+
+export function hashOf(content: Buffer | string): string {
+  return createHash("sha256").update(content).digest("hex")
+}

package/src/services/vault/filesystem/index.ts

@@ -0,0 +1,5 @@
+export * from "./failures.ts"
+export * from "./hash.ts"
+export * from "./read.ts"
+export * from "./types.ts"
+export * from "./write.ts"

package/src/services/vault/filesystem/read.ts

@@ -0,0 +1,61 @@
+import { lstat, readdir, readFile, realpath } from "node:fs/promises"
+
+import { readFailure } from "./failures.ts"
+import type { EntriesResult, ExistingFileResult, RawFileResult, RealPathResult, StatResult } from "./types.ts"
+
+export async function readRawFile(path: string): Promise<RawFileResult> {
+  try {
+    return { succeeded: true, output: await readFile(path) }
+  } catch (error) {
+    if (error instanceof Error) {
+      return readFailure(error, path)
+    }
+    throw error
+  }
+}
+
+export async function linkStatOf(path: string): Promise<StatResult> {
+  try {
+    return { succeeded: true, output: await lstat(path) }
+  } catch (error) {
+    if (error instanceof Error) {
+      return readFailure(error, path)
+    }
+    throw error
+  }
+}
+
+export async function realPathOf(path: string): Promise<RealPathResult> {
+  try {
+    return { succeeded: true, output: await realpath(path) }
+  } catch (error) {
+    if (error instanceof Error) {
+      return readFailure(error, path)
+    }
+    throw error
+  }
+}
+
+export async function directoryEntriesOf(path: string): Promise<EntriesResult> {
+  try {
+    return { succeeded: true, output: await readdir(path, { withFileTypes: true }) }
+  } catch (error) {
+    if (error instanceof Error) {
+      return readFailure(error, path)
+    }
+    throw error
+  }
+}
+
+export async function findFileIgnoringCase(directory: string, fileName: string): Promise<ExistingFileResult> {
+  const entries = await directoryEntriesOf(directory)
+  if (!entries.succeeded) {
+    return entries
+  }
+
+  const found = entries.output.find((entry) => entry.name.toLowerCase() === fileName.toLowerCase())
+  if (found) {
+    return { succeeded: true, output: found.name }
+  }
+  return { succeeded: false, reason: "not-found", code: "ENOENT", problems: [`${fileName} does not exist`] }
+}

package/src/services/vault/filesystem/types.ts

@@ -0,0 +1,36 @@
+import type { Dirent, Stats } from "node:fs"
+
+import type { Done, Failed, Succeeded } from "#src/shared"
+
+interface MissingFile extends Failed {
+  reason: "not-found"
+  code: string
+}
+
+interface NotDirectory extends Failed {
+  reason: "not-directory"
+  code: string
+}
+
+interface NotReadable extends Failed {
+  reason: "not-readable"
+  code: string
+}
+
+export type ReadFailure = MissingFile | NotDirectory | NotReadable
+
+export interface WriteFailure extends Failed {
+  reason: "not-found" | "not-directory" | "not-writable" | "exists"
+  code: string
+}
+
+export interface FileWarnings {
+  maintenanceProblems?: string[]
+}
+
+export type RawFileResult = Succeeded<Buffer> | ReadFailure
+export type StatResult = Succeeded<Stats> | ReadFailure
+export type RealPathResult = Succeeded<string> | ReadFailure
+export type EntriesResult = Succeeded<Dirent[]> | ReadFailure
+export type ExistingFileResult = Succeeded<string> | ReadFailure
+export type WriteResult = (Done & FileWarnings) | WriteFailure

package/src/services/vault/filesystem/write.ts

@@ -0,0 +1,80 @@
+import { randomUUID } from "node:crypto"
+import { link, mkdir, rename, rm, writeFile } from "node:fs/promises"
+import { basename, dirname, join } from "node:path"
+
+import { writeFailure } from "./failures.ts"
+import type { WriteResult } from "./types.ts"
+
+export async function publishExclusively(path: string, text: string): Promise<WriteResult> {
+  return publish(path, text, "create")
+}
+
+export async function writeAtomically(path: string, text: string): Promise<WriteResult> {
+  return publish(path, text, "replace")
+}
+
+async function publish(path: string, text: string, mode: "create" | "replace"): Promise<WriteResult> {
+  const temporary = join(dirname(path), `.${basename(path)}.tmp-${randomUUID()}`)
+  let result: WriteResult
+  let cleanupProblems: string[] = []
+  try {
+    await writeFile(temporary, text, { flag: "wx" })
+    if (mode === "create") {
+      await link(temporary, path)
+    } else {
+      await rename(temporary, path)
+    }
+    result = { succeeded: true }
+  } catch (error) {
+    if (!(error instanceof Error)) {
+      throw error
+    }
+    result = writeFailure(error, path)
+  } finally {
+    cleanupProblems = await cleanupTemporary(temporary)
+  }
+
+  if (cleanupProblems.length === 0) {
+    return result
+  }
+  if (result.succeeded) {
+    return { ...result, maintenanceProblems: cleanupProblems }
+  }
+  return { ...result, problems: [...result.problems, ...cleanupProblems] }
+}
+
+async function cleanupTemporary(path: string): Promise<string[]> {
+  try {
+    await rm(path, { force: true })
+    return []
+  } catch (error) {
+    if (error instanceof Error) {
+      return [`Temporary file ${path} could not be removed: ${error.message}`]
+    }
+    return [`Temporary file ${path} could not be removed`]
+  }
+}
+
+export async function createDirectory(path: string): Promise<WriteResult> {
+  try {
+    await mkdir(path, { recursive: true })
+    return { succeeded: true }
+  } catch (error) {
+    if (error instanceof Error) {
+      return writeFailure(error, path)
+    }
+    throw error
+  }
+}
+
+export async function removeFile(path: string): Promise<WriteResult> {
+  try {
+    await rm(path)
+    return { succeeded: true }
+  } catch (error) {
+    if (error instanceof Error) {
+      return writeFailure(error, path)
+    }
+    throw error
+  }
+}

package/src/services/vault/find.ts

@@ -0,0 +1,27 @@
+import type { VaultContext } from "#src/services/vault/context"
+import { findFileIgnoringCase } from "#src/services/vault/filesystem"
+import { NOTE_EXTENSION } from "./constants.ts"
+import { displayNotePath } from "./display.ts"
+import { noteFileName } from "./paths.ts"
+import { readNote } from "./read.ts"
+import { resolveFolder } from "./resolve.ts"
+import type { ReadNoteResult } from "./types.ts"
+
+export async function findNote(vault: VaultContext, folder: string, statement: string): Promise<ReadNoteResult> {
+  const directory = await resolveFolder(vault.path, folder)
+  if (!directory.succeeded) {
+    return directory
+  }
+
+  const existing = await findFileIgnoringCase(directory.output, noteFileName(statement))
+  if (!existing.succeeded) {
+    if (existing.reason !== "not-found") {
+      return existing
+    }
+
+    return { succeeded: false, reason: "not-found", problems: [`${displayNotePath(folder, statement)} does not exist`] }
+  }
+
+  const realStatement = existing.output.slice(0, -NOTE_EXTENSION.length)
+  return readNote(vault, folder, realStatement)
+}

package/src/services/vault/folder-contents.ts

@@ -0,0 +1,31 @@
+import { ARCHIVE_FOLDER, type FolderContents } from "#src/domain"
+import type { NamedVaultContext } from "#src/services/vault/context"
+import { findFileIgnoringCase, linkStatOf } from "#src/services/vault/filesystem"
+import { resolveFolder } from "./resolve.ts"
+import type { FolderListing } from "./types.ts"
+
+export async function contentsOf(
+  context: NamedVaultContext,
+  folder: string,
+  listing: FolderListing,
+): Promise<FolderContents> {
+  if (folder.length === 0) {
+    return { kind: "root", vaultName: context.name, ...listing, hasArchive: await hasArchive(context.path) }
+  }
+  return { kind: "subject", path: folder, ...listing }
+}
+
+async function hasArchive(vault: string): Promise<boolean> {
+  const existing = await findFileIgnoringCase(vault, ARCHIVE_FOLDER)
+  if (!existing.succeeded) {
+    return false
+  }
+
+  const resolved = await resolveFolder(vault, existing.output)
+  if (!resolved.succeeded) {
+    return false
+  }
+
+  const stat = await linkStatOf(resolved.output)
+  return stat.succeeded && stat.output.isDirectory()
+}

package/src/services/vault/folder-index/index.ts

@@ -0,0 +1,2 @@
+export * from "./read.ts"
+export * from "./types.ts"

package/src/services/vault/folder-index/read.ts

@@ -0,0 +1,87 @@
+import { readdir } from "node:fs/promises"
+
+import { catalogFileKind, isCatalogHidden, isRootTemplate } from "#src/domain"
+import {
+  catalogFailure,
+  catalogIoFailure,
+  observeVaultPath,
+  type ResolvedCatalogEntry,
+  readCatalogBytes,
+} from "#src/services/vault/catalog"
+import type { VaultContext } from "#src/services/vault/context"
+import type { FolderIndexPathResult, FolderIndexRequest, FolderIndexResult } from "./types.ts"
+
+export async function readFolderIndex(vault: VaultContext, request: FolderIndexRequest): Promise<FolderIndexResult> {
+  const folder = await observeVaultPath(vault, { path: request.folder })
+  if (!folder.succeeded) return folder
+  if (folder.output.kind !== "directory") {
+    return catalogFailure({
+      path: request.folder,
+      scope: "directory",
+      reason: "not-directory",
+      problem: "Expected a folder",
+    })
+  }
+  const index = await findFolderIndex(folder.output, request)
+  if (!index.succeeded) return index
+  return readSelectedIndex(vault, index.output)
+}
+
+async function readSelectedIndex(vault: VaultContext, path: string): Promise<FolderIndexResult> {
+  const entry = await observeVaultPath(vault, { path })
+  if (!entry.succeeded) return entry
+  if (!isReadableIndex(entry.output.canonicalPath)) {
+    return catalogFailure({
+      path,
+      scope: "file",
+      reason: "excluded",
+      problem: "The index target is not a readable folder index",
+    })
+  }
+  const bytes = await readCatalogBytes(vault, { path, expectedStat: entry.output.stat })
+  if (!bytes.succeeded) return bytes
+  return {
+    succeeded: true,
+    output: {
+      ...bytes.output,
+      canonicalPath: entry.output.canonicalPath,
+      text: Buffer.from(bytes.output.bytes).toString("utf8"),
+    },
+  }
+}
+
+function isReadableIndex(path: string): boolean {
+  return catalogFileKind(path) === "index" && !isCatalogHidden(path) && !isRootTemplate(path)
+}
+
+async function findFolderIndex(
+  folder: ResolvedCatalogEntry,
+  request: FolderIndexRequest,
+): Promise<FolderIndexPathResult> {
+  try {
+    const names = (await readdir(folder.absolutePath)).filter((name) => name.toLowerCase() === "index.md")
+    if (names.length > 1) {
+      return {
+        succeeded: false,
+        reason: "ambiguous-index",
+        path: request.folder,
+        problems: ["Multiple case-variant folder indexes exist; keep exactly one index.md"],
+      }
+    }
+    const name = names[0]
+    if (!name) {
+      return catalogFailure({
+        path: request.folder,
+        scope: "directory",
+        reason: "not-found",
+        problem: "Folder index is missing; this read does not create it",
+      })
+    }
+    let path = name
+    if (request.folder !== "") path = `${request.folder.replace(/\/$/, "")}/${name}`
+    return { succeeded: true, output: path }
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path: request.folder, scope: "directory" })
+    throw error
+  }
+}

package/src/services/vault/folder-index/types.ts

@@ -0,0 +1,19 @@
+import type { VaultCatalogFailure, VaultExportFile } from "#src/domain"
+import type { Failed, Succeeded } from "#src/shared"
+
+export interface FolderIndexRequest {
+  folder: string
+}
+
+export interface FolderIndex extends VaultExportFile {
+  text: string
+  canonicalPath: string
+}
+
+export interface AmbiguousFolderIndex extends Failed {
+  reason: "ambiguous-index"
+  path: string
+}
+
+export type FolderIndexResult = Succeeded<FolderIndex> | VaultCatalogFailure | AmbiguousFolderIndex
+export type FolderIndexPathResult = Succeeded<string> | VaultCatalogFailure | AmbiguousFolderIndex

package/src/services/vault/folder-listing.ts

@@ -0,0 +1 @@
+export { FOLDER_INDEX_FORMAT, type FolderListingFingerprint, folderListingFingerprints } from "#src/domain"

package/src/services/vault/index.ts

@@ -0,0 +1,21 @@
+export * from "./archive.ts"
+export * from "./bootstrap/index.ts"
+export * from "./catalog/index.ts"
+export * from "./complete-blank.ts"
+export * from "./context/index.ts"
+export * from "./create.ts"
+export * from "./display.ts"
+export * from "./domain-rules.ts"
+export * from "./draft.ts"
+export * from "./find.ts"
+export * from "./folder-index/index.ts"
+export * from "./folder-listing.ts"
+export * from "./inspect-folder.ts"
+export * from "./list.ts"
+export * from "./read.ts"
+export * from "./refresh.ts"
+export * from "./refresh-folders.ts"
+export * from "./succeed.ts"
+export * from "./types.ts"
+export * from "./update.ts"
+export * from "./write-new-file.ts"

package/src/services/vault/inspect-folder.ts

@@ -0,0 +1,13 @@
+import { directoryEntriesOf } from "#src/services/vault/filesystem"
+import type { VaultFolderResult } from "./types.ts"
+
+export async function inspectVaultFolder(path: string): Promise<VaultFolderResult> {
+  const entries = await directoryEntriesOf(path)
+  if (entries.succeeded) {
+    if (entries.output.length === 0) return { succeeded: true, output: "empty" }
+    return { succeeded: true, output: "populated" }
+  }
+  if (entries.reason === "not-found") return { succeeded: true, output: "missing" }
+  if (entries.reason === "not-directory") return { succeeded: true, output: "not-directory" }
+  return { succeeded: false, reason: "io-error", problems: entries.problems }
+}

package/src/services/vault/list.ts

@@ -0,0 +1,121 @@
+import type { Dirent } from "node:fs"
+
+import { ARCHIVE_FOLDER, joinVaultPath, TEMPLATES_FOLDER } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { directoryEntriesOf, linkStatOf } from "#src/services/vault/filesystem"
+import { FOLDER_INDEX_FILE_NAME, NOTE_EXTENSION } from "./constants.ts"
+import { readResolvedNote } from "./read.ts"
+import { resolveFile, resolveFolder } from "./resolve.ts"
+import type { ListingDraft, ReadNoteResult, SettledListResult } from "./types.ts"
+
+export async function listSettledFolder(vault: VaultContext, folder: string): Promise<SettledListResult> {
+  const directory = await resolveFolder(vault.path, folder)
+  if (!directory.succeeded) {
+    return directory
+  }
+
+  const entries = await directoryEntriesOf(directory.output)
+  if (!entries.succeeded) {
+    return entries
+  }
+
+  const draft: ListingDraft = { subjects: [], notes: [], invalid: [], settled: true }
+  for (const entry of entries.output) {
+    await addEntry(draft, vault, folder, entry)
+  }
+  const { settled, ...listing } = draft
+  return { succeeded: true, output: { listing, settled } }
+}
+
+async function addEntry(listing: ListingDraft, vault: VaultContext, folder: string, entry: Dirent): Promise<void> {
+  if (entry.isDirectory()) {
+    await addSubject(listing, vault.path, folder, entry.name)
+  } else if (entry.isSymbolicLink()) {
+    await addLink(listing, vault, folder, entry.name)
+  } else if (entry.isFile()) {
+    await addNote(listing, vault, folder, entry.name)
+  }
+}
+
+async function addLink(listing: ListingDraft, vault: VaultContext, folder: string, name: string): Promise<void> {
+  const resolved = await resolveFile(vault.path, folder, name)
+  if (!resolved.succeeded) {
+    addEntryProblem(listing, name, resolved.problems)
+    return
+  }
+
+  const stat = await linkStatOf(resolved.output)
+  if (!stat.succeeded) {
+    addEntryProblem(listing, name, stat.problems)
+  } else if (stat.output.isDirectory()) {
+    await addSubject(listing, vault.path, folder, name)
+  } else if (stat.output.isFile()) {
+    await addNote(listing, vault, folder, name)
+  }
+}
+
+async function addNote(listing: ListingDraft, vault: VaultContext, folder: string, name: string): Promise<void> {
+  if (!isNoteName(name)) {
+    return
+  }
+
+  const statement = name.slice(0, -NOTE_EXTENSION.length)
+  const path = await resolveFile(vault.path, folder, name)
+  if (!path.succeeded) {
+    addEntryProblem(listing, name, path.problems)
+    return
+  }
+
+  addToListing(listing, statement, await readResolvedNote(vault, folder, statement, path.output))
+}
+
+function addToListing(listing: ListingDraft, statement: string, read: ReadNoteResult): void {
+  if (read.succeeded) {
+    listing.notes.push(read.output.note)
+    return
+  }
+
+  listing.invalid.push({ statement, problems: read.problems })
+  if (read.reason !== "invalid" && read.reason !== "needs-fixing") {
+    listing.settled = false
+  }
+}
+
+async function addSubject(listing: ListingDraft, vault: string, folder: string, name: string): Promise<void> {
+  if (name.startsWith(".")) {
+    return
+  }
+  if (folder.length === 0 && [ARCHIVE_FOLDER, TEMPLATES_FOLDER].includes(name.toLowerCase())) {
+    return
+  }
+
+  const checked = await resolveFolder(vault, joinVaultPath(folder, name))
+  if (!checked.succeeded) {
+    addFolderProblem(listing, name, checked.problems)
+    return
+  }
+
+  listing.subjects.push(name)
+}
+
+function addEntryProblem(listing: ListingDraft, name: string, problems: string[]): void {
+  if (isNoteName(name)) {
+    listing.settled = false
+    listing.invalid.push({ statement: name.slice(0, -NOTE_EXTENSION.length), problems })
+  } else if (!name.startsWith(".")) {
+    addFolderProblem(listing, name, problems)
+  }
+}
+
+function addFolderProblem(listing: ListingDraft, folder: string, problems: string[]): void {
+  listing.settled = false
+  if (!listing.problemFolders) {
+    listing.problemFolders = []
+  }
+  listing.problemFolders.push({ folder, problems })
+}
+
+function isNoteName(name: string): boolean {
+  const lower = name.toLowerCase()
+  return lower.endsWith(NOTE_EXTENSION) && lower !== FOLDER_INDEX_FILE_NAME
+}

package/src/services/vault/memory-folder.ts

@@ -0,0 +1,24 @@
+import { relative, sep } from "node:path"
+
+import { checkMemoryFolder } from "#src/domain"
+import { resolveFolder } from "./resolve.ts"
+import type { ResolveResult } from "./types.ts"
+
+export async function resolveMemoryFolder(vault: string, folder: string): Promise<ResolveResult> {
+  const directory = await resolveFolder(vault, folder)
+  if (!directory.succeeded) {
+    return directory
+  }
+
+  const root = await resolveFolder(vault, "")
+  if (!root.succeeded) {
+    return root
+  }
+
+  const actualFolder = relative(root.output, directory.output).split(sep).join("/")
+  const problems = checkMemoryFolder(actualFolder)
+  if (problems.length > 0) {
+    return { succeeded: false, reason: "invalid", problems }
+  }
+  return directory
+}

package/src/services/vault/paths.ts

@@ -0,0 +1,11 @@
+import { NOTE_EXTENSION } from "./constants.ts"
+import type { StoredFilePath } from "./types.ts"
+
+export function storedFilePath(path: string): StoredFilePath {
+  const separator = path.lastIndexOf("/")
+  return { folder: path.slice(0, Math.max(0, separator)), fileName: path.slice(separator + 1) }
+}
+
+export function noteFileName(statement: string): string {
+  return `${statement}${NOTE_EXTENSION}`
+}