pi-obsidian-memory 0.0.1 → 0.1.1

package/src/services/vault/catalog/resolve.ts

@@ -0,0 +1,94 @@
+import type { Dirent } from "node:fs"
+import { lstat, realpath, stat } from "node:fs/promises"
+import { isAbsolute, join, relative, sep } from "node:path"
+
+import { isSafeCatalogPath } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { catalogFailure, catalogIoFailure } from "./failures.ts"
+import { catalogEntryKind, catalogStat } from "./stat.ts"
+import type { CatalogLocation, CatalogResolveResult, CatalogRootResult } from "./types.ts"
+
+export async function resolveCatalogRoot(vault: VaultContext): Promise<CatalogRootResult> {
+  try {
+    const root = await realpath(vault.path)
+    if (!(await stat(root)).isDirectory()) {
+      return catalogFailure({
+        path: "",
+        scope: "directory",
+        reason: "not-directory",
+        problem: "The vault root is not a directory",
+      })
+    }
+    return { succeeded: true, output: root }
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path: "", scope: "directory" })
+    throw error
+  }
+}
+
+export async function resolveCatalogEntry(location: CatalogLocation): Promise<CatalogResolveResult> {
+  if (location.path !== "" && !isSafeCatalogPath(location.path)) {
+    return catalogFailure({
+      path: location.path,
+      scope: "entry",
+      reason: "invalid-path",
+      problem: "Expected a safe vault-relative path with / separators",
+    })
+  }
+  try {
+    const resolved = await resolveComponents(location)
+    if (!resolved.succeeded) return resolved
+    const stats = await stat(resolved.output)
+    return {
+      succeeded: true,
+      output: {
+        absolutePath: resolved.output,
+        canonicalPath: relative(location.root, resolved.output).split(sep).join("/"),
+        kind: catalogEntryKind(stats),
+        stat: catalogStat(stats),
+      },
+    }
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path: location.path, scope: "entry" })
+    throw error
+  }
+}
+
+export async function resolveListedEntry(location: CatalogLocation, listed: Dirent): Promise<CatalogResolveResult> {
+  if (!(listed.isFile() || listed.isDirectory()) || !isSafeCatalogPath(location.path)) {
+    return resolveCatalogEntry(location)
+  }
+  const absolutePath = join(location.root, ...location.path.split("/"))
+  try {
+    const stats = await lstat(absolutePath)
+    if (stats.isSymbolicLink()) return resolveCatalogEntry(location)
+    return {
+      succeeded: true,
+      output: { absolutePath, canonicalPath: location.path, kind: catalogEntryKind(stats), stat: catalogStat(stats) },
+    }
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path: location.path, scope: "entry" })
+    throw error
+  }
+}
+
+async function resolveComponents(location: CatalogLocation): Promise<CatalogRootResult> {
+  let current = location.root
+  for (const part of location.path.split("/").filter((part) => part !== "")) {
+    current = await realpath(join(current, part))
+    if (!isCatalogInside(location.root, current)) {
+      return catalogFailure({
+        path: location.path,
+        scope: "entry",
+        reason: "outside-vault",
+        problem: "The path leads outside the real vault root",
+      })
+    }
+  }
+  return { succeeded: true, output: current }
+}
+
+export function isCatalogInside(root: string, path: string): boolean {
+  const rel = relative(root, path)
+  return !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`)
+}

package/src/services/vault/catalog/stat.ts

@@ -0,0 +1,23 @@
+import type { Stats } from "node:fs"
+
+import type { VaultFileStat } from "#src/domain"
+import type { ResolvedCatalogEntry } from "./types.ts"
+
+export function catalogStat(stats: Stats): VaultFileStat {
+  return { size: stats.size, mtimeMs: stats.mtimeMs, ctimeMs: stats.ctimeMs, device: stats.dev, inode: stats.ino }
+}
+
+export function catalogEntryKind(stats: Stats): ResolvedCatalogEntry["kind"] {
+  if (stats.isFile()) return "file"
+  if (stats.isDirectory()) return "directory"
+  return "other"
+}
+
+export function sameCatalogStat(left: VaultFileStat, right: VaultFileStat): boolean {
+  return (
+    left.size === right.size &&
+    left.mtimeMs === right.mtimeMs &&
+    left.device === right.device &&
+    left.inode === right.inode
+  )
+}

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

@@ -0,0 +1,69 @@
+import type { VaultCatalogFailure, VaultEnumeration, VaultExportFile, VaultFileStat } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import type { Succeeded } from "#src/shared"
+
+export type {
+  InspectedVaultFile,
+  ParsedVaultNote,
+  UnclosedVaultNote,
+  VaultAlias,
+  VaultCatalogEntry,
+  VaultCatalogFailure,
+  VaultEntryKind,
+  VaultEnumeration,
+  VaultEnumerationResult,
+  VaultExportFailure,
+  VaultExportFile,
+  VaultExportResult,
+  VaultFileRequest,
+  VaultFileStat,
+  VaultInspectionResult,
+  VaultNoteAnalysis,
+  VaultNoteProblems,
+} from "#src/domain"
+
+export interface CatalogLocation {
+  root: string
+  path: string
+}
+
+export interface ResolvedCatalogEntry {
+  absolutePath: string
+  canonicalPath: string
+  kind: "file" | "directory" | "other"
+  stat: VaultFileStat
+}
+
+export interface CatalogFailureDetail {
+  path: string
+  scope: VaultCatalogFailure["scope"]
+  reason: VaultCatalogFailure["reason"]
+  problem: string
+}
+
+export interface CatalogOperation {
+  path: string
+  scope: VaultCatalogFailure["scope"]
+}
+
+export type CatalogRootResult = Succeeded<string> | VaultCatalogFailure
+export type CatalogResolveResult = Succeeded<ResolvedCatalogEntry> | VaultCatalogFailure
+export type CatalogBytesResult = Succeeded<VaultExportFile> | VaultCatalogFailure
+
+export interface CatalogReadRequest {
+  path: string
+  expectedStat?: VaultFileStat
+}
+
+export interface CatalogWalk {
+  vault: VaultContext
+  root: string
+  mode: "memory" | "export"
+  pending: string[]
+  inventory: VaultEnumeration
+}
+
+export interface CatalogWalkRequest {
+  vault: VaultContext
+  mode: CatalogWalk["mode"]
+}

package/src/services/vault/catalog/visit.ts

@@ -0,0 +1,58 @@
+import { catalogFileKind, isCatalogHidden, isCatalogNotePath, isRootArchive, isRootTemplate } from "#src/domain"
+import { catalogFailure } from "./failures.ts"
+import type { CatalogResolveResult, CatalogWalk, ResolvedCatalogEntry } from "./types.ts"
+
+export function visitCatalogEntry(walk: CatalogWalk, path: string, result: CatalogResolveResult): void {
+  if (!result.succeeded) {
+    walk.inventory.failures.push(result)
+    return
+  }
+
+  const entry = result.output
+  if (entry.kind === "directory" && isCatalogHidden(path)) return
+
+  if (entry.canonicalPath !== path) {
+    recordAlias(walk, path, entry)
+    return
+  }
+  recordPhysicalEntry(walk, entry)
+}
+
+function recordPhysicalEntry(walk: CatalogWalk, entry: ResolvedCatalogEntry): void {
+  const path = entry.canonicalPath
+  if (entry.kind === "directory") {
+    walk.inventory.entries.push({ path, kind: "folder", archived: isRootArchive(path), stat: entry.stat })
+    if (walk.mode === "export" || !isRootTemplate(path)) walk.pending.push(path)
+    return
+  }
+  if (entry.kind !== "file") {
+    walk.inventory.failures.push(
+      catalogFailure({ path, scope: "entry", reason: "not-file", problem: "Not a regular file or directory" }),
+    )
+    return
+  }
+  walk.inventory.entries.push({
+    path,
+    kind: catalogFileKind(path),
+    archived: isRootArchive(path),
+    stat: entry.stat,
+  })
+}
+
+function recordAlias(walk: CatalogWalk, path: string, entry: ResolvedCatalogEntry): void {
+  const target = entry.canonicalPath
+  if (entry.kind === "directory" && (target === "" || path.startsWith(`${target}/`))) {
+    walk.inventory.failures.push(
+      catalogFailure({ path, scope: "directory", reason: "cycle", problem: "Directory alias leads to an ancestor" }),
+    )
+    return
+  }
+  const memoryNote = walk.mode === "memory" && entry.kind === "file" && isCatalogNotePath(target)
+  if (isCatalogHidden(target) && !memoryNote) {
+    walk.inventory.failures.push(
+      catalogFailure({ path, scope: "entry", reason: "excluded", problem: "Alias leads to a hidden path" }),
+    )
+    return
+  }
+  walk.inventory.aliases.push({ path, target })
+}

package/src/services/vault/complete-blank.ts

@@ -0,0 +1,66 @@
+import { checkMemoryFolder, type Note, parseNote } from "#src/domain"
+import { inspectVaultFile } from "#src/services/vault/catalog"
+import type { VaultContext } from "#src/services/vault/context"
+import type { Succeeded } from "#src/shared"
+import type { BlankCompletionRefusal, CompleteBlankRequest, CompleteBlankResult } from "./types.ts"
+import { updateNoteFile } from "./update-file.ts"
+
+export async function completeBlankFile(
+  vault: VaultContext,
+  request: CompleteBlankRequest,
+): Promise<CompleteBlankResult> {
+  const inspected = await inspectVaultFile(vault, { path: request.path })
+  if (!inspected.succeeded) return inspected
+  const current = inspected.output
+  if (current.rawHash !== request.expectedHash) {
+    return { succeeded: false, reason: "conflict", problems: ["The blank file changed since its preview"] }
+  }
+  const note = noteToComplete(request.note, current.text)
+  if (!note.succeeded) return note
+
+  return completeInspectedBlank(vault, { ...request, note: note.output }, current.canonicalPath)
+}
+
+function noteToComplete(note: Note, text: string): Succeeded<Note> | BlankCompletionRefusal {
+  if (text.trim() === "") return { succeeded: true, output: note }
+  const parsed = parseNote(note.statement, text)
+  if (parsed.succeeded) {
+    return { succeeded: false, reason: "not-blank", problems: ["The file already has frontmatter"] }
+  }
+  if (parsed.problems.includes("frontmatter is not closed")) {
+    return { succeeded: false, reason: "not-blank", problems: parsed.problems }
+  }
+  const normalized = text.replaceAll("\r\n", "\n")
+  return { succeeded: true, output: { ...note, body: withoutFinalNewline(normalized) } }
+}
+
+function withoutFinalNewline(text: string): string {
+  if (text.endsWith("\n")) return text.slice(0, -1)
+  return text
+}
+
+async function completeInspectedBlank(
+  vault: VaultContext,
+  request: CompleteBlankRequest,
+  canonicalPath: string,
+): Promise<CompleteBlankResult> {
+  const folder = canonicalPath.slice(0, Math.max(0, canonicalPath.lastIndexOf("/")))
+  const requestedFolder = request.path.slice(0, Math.max(0, request.path.lastIndexOf("/")))
+  const problems = [...checkMemoryFolder(folder), ...checkMemoryFolder(requestedFolder)]
+  if (problems.length > 0) return { succeeded: false, reason: "invalid", problems }
+  const fileName = canonicalPath.slice(canonicalPath.lastIndexOf("/") + 1)
+  const requestedName = request.path.slice(request.path.lastIndexOf("/") + 1)
+  if (
+    fileName.slice(-3).toLowerCase() !== ".md" ||
+    fileName.slice(0, -3) !== request.note.statement ||
+    requestedName !== fileName
+  ) {
+    return {
+      succeeded: false,
+      reason: "path-mismatch",
+      problems: ["The candidate statement must match the blank file"],
+    }
+  }
+
+  return updateNoteFile(vault, { folder, fileName, note: request.note, expectedHash: request.expectedHash })
+}

package/src/services/vault/constants.ts

@@ -0,0 +1,3 @@
+export const NOTE_EXTENSION = ".md"
+
+export const FOLDER_INDEX_FILE_NAME = "index.md"

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

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

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

@@ -0,0 +1,10 @@
+import type { NoteLimits } from "#src/domain"
+
+export interface VaultContext {
+  path: string
+  limits: NoteLimits
+}
+
+export interface NamedVaultContext extends VaultContext {
+  name: string
+}

package/src/services/vault/create.ts

@@ -0,0 +1,19 @@
+import { checkMemoryFolder, checkNote, type Note } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { resolveMemoryFolder } from "./memory-folder.ts"
+import { writeValidatedNote } from "./publish.ts"
+import type { CreateResult } from "./types.ts"
+
+export async function createMemoryNote(vault: VaultContext, folder: string, note: Note): Promise<CreateResult> {
+  const problems = [...checkMemoryFolder(folder), ...checkNote(note, vault.limits)]
+  if (problems.length > 0) {
+    return { succeeded: false, reason: "invalid", problems }
+  }
+
+  const directory = await resolveMemoryFolder(vault.path, folder)
+  if (!directory.succeeded) {
+    return directory
+  }
+
+  return writeValidatedNote(vault.path, folder, note)
+}

package/src/services/vault/display.ts

@@ -0,0 +1,6 @@
+import { joinVaultPath } from "#src/domain"
+import { noteFileName } from "./paths.ts"
+
+export function displayNotePath(folder: string, statement: string): string {
+  return joinVaultPath(folder, noteFileName(statement))
+}

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)
+}