pi-obsidian-memory 0.0.0 → 0.1.0

package/src/services/vault/resolve.ts

@@ -0,0 +1,109 @@
+import { isAbsolute, join, relative, sep } from "node:path"
+
+import { checkFileName, checkVaultPath, joinVaultPath, VAULT_PATH_SEPARATOR } from "#src/domain"
+import { linkStatOf, realPathOf } from "#src/services/vault/filesystem"
+import type { ResolveResult } from "./types.ts"
+
+export async function resolveFolder(vault: string, folder: string): Promise<ResolveResult> {
+  return resolveParts(vault, checkVaultPath(folder), partsOf(folder), "directory")
+}
+
+export async function resolveFile(vault: string, folder: string, fileName: string): Promise<ResolveResult> {
+  const problems = [...checkVaultPath(folder), ...checkFileName(fileName)]
+  return resolveParts(vault, problems, [...partsOf(folder), fileName], "file")
+}
+
+async function resolveParts(
+  vault: string,
+  problems: string[],
+  parts: string[],
+  kind: "directory" | "file",
+): Promise<ResolveResult> {
+  if (problems.length > 0) {
+    return { succeeded: false, reason: "invalid", problems }
+  }
+
+  const root = await resolveRoot(vault)
+  if (!root.succeeded) {
+    return root
+  }
+
+  let current = root.output
+  for (const [depth, part] of parts.entries()) {
+    const path = join(current, part)
+    const target = await resolveEntry(root.output, path, joinVaultPath(...parts.slice(0, depth + 1)))
+    if (!target.succeeded) {
+      return target
+    }
+
+    const stat = await linkStatOf(target.output)
+    if (!stat.succeeded) {
+      if (stat.reason === "not-found") {
+        return { succeeded: true, output: join(target.output, ...parts.slice(depth + 1)) }
+      }
+      return stat
+    }
+    if ((depth < parts.length - 1 || kind === "directory") && !stat.output.isDirectory()) {
+      return { succeeded: false, reason: "not-directory", problems: [`${path} is not a directory`] }
+    }
+
+    current = target.output
+  }
+  return { succeeded: true, output: current }
+}
+
+async function resolveRoot(vault: string): Promise<ResolveResult> {
+  const root = await realPathOf(vault)
+  if (!root.succeeded) {
+    if (root.reason === "not-found") {
+      return { succeeded: false, reason: "vault-missing", problems: [`the vault folder ${vault} does not exist`] }
+    }
+    return root
+  }
+
+  const stat = await linkStatOf(root.output)
+  if (!stat.succeeded) {
+    if (stat.reason === "not-found") {
+      return { succeeded: false, reason: "vault-missing", problems: stat.problems }
+    }
+    return stat
+  }
+  if (!stat.output.isDirectory()) {
+    return { succeeded: false, reason: "not-directory", problems: [`the vault ${vault} is not a directory`] }
+  }
+  return root
+}
+
+async function resolveEntry(root: string, path: string, displayPath: string): Promise<ResolveResult> {
+  const stat = await linkStatOf(path)
+  if (!stat.succeeded) {
+    if (stat.reason === "not-found") {
+      return { succeeded: true, output: path }
+    }
+    return stat
+  }
+  if (!stat.output.isSymbolicLink()) {
+    return { succeeded: true, output: path }
+  }
+
+  const target = await realPathOf(path)
+  if (!target.succeeded) {
+    if (target.reason === "not-found" || target.code === "ELOOP") {
+      return { succeeded: false, reason: "outside-vault", problems: [`${displayPath} is a link that does not resolve`] }
+    }
+    return target
+  }
+  if (!isInside(root, target.output)) {
+    return { succeeded: false, reason: "outside-vault", problems: [`${displayPath} leads outside the vault`] }
+  }
+  return target
+}
+
+function isInside(root: string, path: string): boolean {
+  const fromRoot = relative(root, path)
+  return !isAbsolute(fromRoot) && fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`)
+}
+
+function partsOf(folder: string): string[] {
+  return folder.split(VAULT_PATH_SEPARATOR).filter((part) => part.length > 0)
+}

package/src/services/vault/succeed.ts

@@ -0,0 +1,45 @@
+import { checkMemoryFolder, succeedNote } from "#src/domain"
+import type { NamedVaultContext } from "#src/services/vault/context"
+import { resolveMemoryFolder } from "./memory-folder.ts"
+import { relocateNote } from "./relocate.ts"
+import type { ExactSucceedRequest, SucceedRequest, SuccessionResult } from "./types.ts"
+
+export async function succeedStoredNote(vault: NamedVaultContext, request: SucceedRequest): Promise<SuccessionResult> {
+  return succeedOriginal(vault, request, null)
+}
+
+export async function succeedStoredFile(
+  vault: NamedVaultContext,
+  request: ExactSucceedRequest,
+): Promise<SuccessionResult> {
+  return succeedOriginal(vault, request, request.path)
+}
+
+async function succeedOriginal(
+  vault: NamedVaultContext,
+  request: SucceedRequest,
+  originalPath: string | null,
+): Promise<SuccessionResult> {
+  const problems = checkMemoryFolder(request.successor.folder)
+  if (problems.length > 0) {
+    return { succeeded: false, reason: "invalid", problems }
+  }
+
+  const destination = await resolveMemoryFolder(vault.path, request.successor.folder)
+  if (!destination.succeeded) {
+    return destination
+  }
+
+  const succession = succeedNote(request.previous, request.successor, request.today)
+  const relocated = await relocateNote(vault, {
+    original: request.previous,
+    originalPath,
+    hashWhenRead: request.hashWhenRead,
+    written: [succession.archived, succession.successor],
+  })
+  if (!relocated.succeeded) {
+    return relocated
+  }
+
+  return { ...relocated, output: succession }
+}

package/src/services/vault/types.ts

@@ -0,0 +1,199 @@
+import type {
+  InvalidNote,
+  Note,
+  ParsedNote,
+  PlacedNote,
+  ProblemFolder,
+  Succession,
+  VaultCatalogFailure,
+  VaultFileStat,
+} from "#src/domain"
+import type { Done, Failed, Succeeded } from "#src/shared"
+
+export interface ExactUpdateRequest {
+  path: string
+  note: Note
+  expectedHash: string
+}
+
+export interface StoredFilePath {
+  folder: string
+  fileName: string
+}
+
+export interface UpdateFileRequest {
+  folder: string
+  fileName: string
+  note: Note
+  expectedHash: string
+}
+
+export interface CompleteBlankRequest {
+  path: string
+  expectedHash: string
+  note: Note
+  confirmed: true
+}
+
+export interface BlankCompletionRefusal extends Failed {
+  reason: "not-blank" | "path-mismatch"
+}
+
+export type CompleteBlankResult = UpdateResult | BlankCompletionRefusal | VaultCatalogFailure
+
+export interface StoredNote {
+  note: Note
+  hash: string
+}
+
+export interface MaintenanceWarnings {
+  maintenanceProblems?: string[]
+}
+
+export interface FolderListing {
+  subjects: string[]
+  notes: Note[]
+  invalid: InvalidNote[]
+  problemFolders?: ProblemFolder[]
+}
+
+export interface ArchiveRequest {
+  note: PlacedNote
+  hashWhenRead: string
+  today: string
+}
+
+export interface ExactArchiveRequest extends ArchiveRequest {
+  path: string
+}
+
+export interface SucceedRequest {
+  previous: PlacedNote
+  hashWhenRead: string
+  successor: PlacedNote
+  today: string
+}
+
+export interface ExactSucceedRequest extends SucceedRequest {
+  path: string
+}
+
+export interface FileRelocationRequest extends RelocationRequest {
+  originalPath: string | null
+}
+
+export interface RelocationRequest {
+  original: PlacedNote
+  hashWhenRead: string
+  written: [PlacedNote, ...PlacedNote[]]
+}
+
+export interface ResolveRefusal extends Failed {
+  reason: "invalid" | "outside-vault" | "vault-missing" | "not-directory" | "not-readable"
+}
+
+export interface ReadRefusal extends Failed {
+  reason: ResolveRefusal["reason"] | "not-found"
+}
+
+export interface CreateRefusal extends Failed {
+  reason: ResolveRefusal["reason"] | "not-writable" | "not-found"
+}
+
+export interface ExistingNoteRefusal extends Failed {
+  reason: "exists"
+  existingStatement: string
+}
+
+export interface UpdateRefusal extends Failed {
+  reason: CreateRefusal["reason"] | "conflict"
+}
+
+export interface IoRefusal extends Failed {
+  reason: "io-error"
+}
+
+export interface RefreshRefusal extends Failed {
+  reason: CreateRefusal["reason"] | "io-error" | "interrupted"
+}
+
+export interface RefreshPlan {
+  folders: Set<string>
+  refusals: RefreshRefusal[]
+}
+
+export type RefreshContinuation = () => boolean
+export type RefreshScope = "with-ancestors" | "exact"
+
+export type IndexStat = VaultFileStat
+
+export interface RefreshedFolder {
+  folder: string
+  index: IndexStat
+  settled: boolean
+}
+
+export interface RefreshedFolders {
+  refreshed: RefreshedFolder[]
+}
+
+export interface FolderRefreshed extends MaintenanceWarnings {
+  index: IndexStat
+  settled: boolean
+}
+
+export interface ListingDraft extends FolderListing {
+  settled: boolean
+}
+
+export interface SettledListing {
+  listing: FolderListing
+  settled: boolean
+}
+
+export type LifecycleRefusal = UpdateRefusal | ExistingNoteRefusal
+export type VaultRefusal = LifecycleRefusal | IoRefusal
+export type VaultFailureReason = VaultRefusal["reason"]
+
+export interface PartialRelocation extends Failed {
+  reason: "partial"
+  cause: LifecycleRefusal | IoRefusal
+  written: PlacedNote[]
+  originalState: "present" | "missing" | "unknown"
+}
+
+export interface RelocationProgress {
+  written: PlacedNote[]
+  maintenanceProblems: string[]
+}
+
+export interface NeedsFixingNote extends Failed {
+  reason: "needs-fixing"
+  parsed: ParsedNote
+  hash: string
+}
+
+export type CreateResult = (Succeeded<StoredNote> & MaintenanceWarnings) | CreateRefusal | ExistingNoteRefusal
+export type UpdateResult = (Succeeded<StoredNote> & MaintenanceWarnings) | UpdateRefusal
+export type VaultResult = CreateResult | UpdateResult
+export type ReadNoteResult = Succeeded<StoredNote> | ReadRefusal | NeedsFixingNote
+export type CheckResult = Done | LifecycleRefusal
+export type RemovalResult = Succeeded<string> | LifecycleRefusal
+export type RelocationWriteResult = RemovalResult | PartialRelocation
+export type RelocationResult = (Done & MaintenanceWarnings) | LifecycleRefusal | PartialRelocation
+export type PlacedResult = (Succeeded<PlacedNote> & MaintenanceWarnings) | LifecycleRefusal | PartialRelocation
+export type SuccessionResult = (Succeeded<Succession> & MaintenanceWarnings) | LifecycleRefusal | PartialRelocation
+export type RefreshResult = (Done & MaintenanceWarnings) | RefreshRefusal
+export type FolderRefreshResult = RefreshResult & RefreshedFolders
+export type FolderRefreshOutcome = Succeeded<FolderRefreshed> | RefreshRefusal
+export type ResolveResult = Succeeded<string> | ResolveRefusal
+export type ListResult = Succeeded<FolderListing> | ReadRefusal
+export type SettledListResult = Succeeded<SettledListing> | ReadRefusal
+export type VaultFolderState = "missing" | "empty" | "populated" | "not-directory"
+export type VaultFolderResult = Succeeded<VaultFolderState> | IoRefusal
+
+export interface NewFileRefusal extends Failed {
+  reason: "exists" | "not-found" | "io-error"
+}
+
+export type WriteNewFileResult = Done | NewFileRefusal

package/src/services/vault/update-file.ts

@@ -0,0 +1,58 @@
+import { checkFileName, checkNote, renderNote } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { hashOf, readRawFile, writeAtomically } from "#src/services/vault/filesystem"
+import { displayNotePath } from "./display.ts"
+import { refuseWrite } from "./refusals.ts"
+import { resolveFile } from "./resolve.ts"
+import { resolveStoredFile } from "./resolve-stored-file.ts"
+import type { ResolveResult, UpdateFileRequest, UpdateResult } from "./types.ts"
+
+export async function updateNoteFile(
+  vault: VaultContext,
+  request: UpdateFileRequest,
+  exactPath?: string,
+): Promise<UpdateResult> {
+  const { folder, fileName, note, expectedHash } = request
+  const problems = [...checkNote(note, vault.limits), ...checkFileName(fileName)]
+  if (fileName.slice(-3).toLowerCase() !== ".md" || fileName.slice(0, -3) !== note.statement) {
+    problems.push("The destination filename must match the note statement and have a Markdown extension")
+  }
+  if (problems.length > 0) {
+    return { succeeded: false, reason: "invalid", problems }
+  }
+
+  const path = await resolveUpdatePath(vault.path, request, exactPath)
+  if (!path.succeeded) {
+    return path
+  }
+
+  const current = await readRawFile(path.output)
+  if (!current.succeeded && current.reason !== "not-found") {
+    return current
+  }
+  if (!current.succeeded || hashOf(current.output) !== expectedHash) {
+    const problem = `${displayNotePath(folder, note.statement)} changed on disk since it was read`
+    return { succeeded: false, reason: "conflict", problems: [problem] }
+  }
+
+  const text = renderNote(note)
+  const written = await writeAtomically(path.output, text)
+  if (!written.succeeded) {
+    return refuseWrite(folder, note.statement, written)
+  }
+
+  const result: UpdateResult = { succeeded: true, output: { note, hash: hashOf(text) } }
+  if (written.maintenanceProblems) {
+    result.maintenanceProblems = written.maintenanceProblems
+  }
+  return result
+}
+
+async function resolveUpdatePath(
+  vault: string,
+  request: UpdateFileRequest,
+  exactPath: string | undefined,
+): Promise<ResolveResult> {
+  if (typeof exactPath === "string") return resolveStoredFile(vault, exactPath, request.note.statement)
+  return resolveFile(vault, request.folder, request.fileName)
+}

package/src/services/vault/update.ts

@@ -0,0 +1,22 @@
+import type { Note } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { noteFileName, storedFilePath } from "./paths.ts"
+import type { ExactUpdateRequest, UpdateResult } from "./types.ts"
+import { updateNoteFile } from "./update-file.ts"
+
+export async function updateStoredFile(vault: VaultContext, request: ExactUpdateRequest): Promise<UpdateResult> {
+  return updateNoteFile(
+    vault,
+    { ...storedFilePath(request.path), note: request.note, expectedHash: request.expectedHash },
+    request.path,
+  )
+}
+
+export async function updateNote(
+  vault: VaultContext,
+  folder: string,
+  note: Note,
+  hashWhenRead: string,
+): Promise<UpdateResult> {
+  return updateNoteFile(vault, { folder, fileName: noteFileName(note.statement), note, expectedHash: hashWhenRead })
+}

package/src/services/vault/write-new-file.ts

@@ -0,0 +1,37 @@
+import { open } from "node:fs/promises"
+
+import { errorCode, removeFile } from "#src/services/vault/filesystem"
+import type { NewFileRefusal, WriteNewFileResult } from "./types.ts"
+
+export async function writeNewFile(path: string, bytes: Uint8Array): Promise<WriteNewFileResult> {
+  let created = false
+  try {
+    const handle = await open(path, "wx")
+    created = true
+    try {
+      await handle.writeFile(bytes)
+    } finally {
+      await handle.close()
+    }
+    return { succeeded: true }
+  } catch (error) {
+    if (!(error instanceof Error)) throw error
+    const refusal = refusalOf(error, path)
+    if (!created) return refusal
+    const removed = await removeFile(path)
+    if (removed.succeeded) return refusal
+    return { ...refusal, problems: [...refusal.problems, ...removed.problems.map(partialFileProblem)] }
+  }
+}
+
+function partialFileProblem(problem: string): string {
+  return `The partly written file was left behind: ${problem}`
+}
+
+function refusalOf(error: Error, path: string): NewFileRefusal {
+  const code = errorCode(error)
+  const problems = [`${path} cannot be created (${code})`]
+  if (code === "EEXIST") return { succeeded: false, reason: "exists", problems }
+  if (code === "ENOENT" || code === "ENOTDIR") return { succeeded: false, reason: "not-found", problems }
+  return { succeeded: false, reason: "io-error", problems }
+}

package/src/shared/index.ts

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

package/src/shared/result/index.ts

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

package/src/shared/result/types.ts

@@ -0,0 +1,17 @@
+export interface Succeeded<Output> {
+  succeeded: true
+  output: Output
+}
+
+export interface Done {
+  succeeded: true
+}
+
+export interface Failed {
+  succeeded: false
+  problems: string[]
+}
+
+export interface Absent {
+  succeeded: false
+}

package/src/usecases/add-memory/add-memory.ts

@@ -0,0 +1,83 @@
+import {
+  createMemoryNote,
+  displayNotePath,
+  type ExistingNoteRefusal,
+  newNote,
+  newNoteId,
+  type ReadNoteResult,
+  readConfig,
+  readNote,
+  targetVault,
+  today,
+} from "#src/services"
+import {
+  captureMemoryOperationContext,
+  type MemoryOperationContext,
+  memoryAdmissionRefusal,
+  memoryOperationInterruption,
+} from "#src/usecases/operation-context"
+import { maintainAddedMemory } from "./maintenance.ts"
+import type { AddMemoryRequest, AddMemoryResult } from "./types.ts"
+
+export async function addMemory(
+  request: AddMemoryRequest,
+  callerContext: MemoryOperationContext,
+): Promise<AddMemoryResult> {
+  const context = captureMemoryOperationContext(callerContext)
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) return memoryAdmissionRefusal(context)
+  try {
+    const interrupted = memoryOperationInterruption(context)
+    if (interrupted) return interrupted
+    return await addLeasedMemory(request, context)
+  } finally {
+    lease.release()
+  }
+}
+
+async function addLeasedMemory(request: AddMemoryRequest, context: MemoryOperationContext): Promise<AddMemoryResult> {
+  const config = await readConfig(context.configPath, context.platform)
+  if (!config.succeeded) {
+    return config
+  }
+
+  const target = targetVault(config.output, request.scope, context.workingFolder, context.platform)
+  if (!target.succeeded) {
+    return { ...target, configPath: context.configPath }
+  }
+
+  const { path, name } = target.output
+  const { limits } = config.output
+  const vault = { path, name, limits }
+  const created = await createMemoryNote(vault, request.folder, newNote(request.draft, newNoteId(), today()))
+  if (!created.succeeded && created.reason === "exists") {
+    const existing = await readNote(vault, request.folder, created.existingStatement)
+    return refuseExisting(created, existing)
+  }
+
+  if (!created.succeeded) {
+    return created
+  }
+
+  const maintenanceProblems = await maintainAddedMemory(vault, request.folder, created)
+  const notePath = displayNotePath(request.folder, created.output.note.statement)
+  return {
+    succeeded: true,
+    output: {
+      scope: request.scope,
+      vaultName: name,
+      folder: request.folder,
+      notePath,
+      stored: created.output,
+      maintenanceProblems,
+    },
+  }
+}
+
+function refuseExisting(refusal: ExistingNoteRefusal, existing: ReadNoteResult): AddMemoryResult {
+  if (!existing.succeeded) {
+    return refusal
+  }
+
+  return { succeeded: false, reason: "exists", problems: refusal.problems, existing: existing.output }
+}

package/src/usecases/add-memory/index.ts

@@ -0,0 +1,4 @@
+export * from "./add-memory.ts"
+export * from "./maintenance.ts"
+export * from "./schemas.ts"
+export * from "./types.ts"

package/src/usecases/add-memory/maintenance.ts

@@ -0,0 +1,23 @@
+import { type CreateResult, type NamedVaultContext, type RefreshResult, refreshIndexes } from "#src/services"
+import type { Done } from "#src/shared"
+
+export async function maintainAddedMemory(
+  vault: NamedVaultContext,
+  folder: string,
+  created: Extract<CreateResult, Done>,
+): Promise<string[]> {
+  const refreshed = await refreshIndexes(vault, folder)
+  return [...maintenanceProblemsOf(created), ...maintenanceProblemsOf(refreshed)]
+}
+
+export function maintenanceProblemsOf(result: CreateResult | RefreshResult): string[] {
+  if (!result.succeeded) {
+    return result.problems.map((problem) => `${result.reason}: ${problem}`)
+  }
+
+  if (result.maintenanceProblems) {
+    return result.maintenanceProblems
+  }
+
+  return []
+}

package/src/usecases/add-memory/schemas.ts

@@ -0,0 +1,12 @@
+import Type from "typebox"
+
+import { MemoryDraftSchema, MemoryScopeSchema } from "#src/services"
+
+export const AddMemoryRequestSchema = Type.Object(
+  {
+    scope: MemoryScopeSchema,
+    folder: Type.String(),
+    draft: MemoryDraftSchema,
+  },
+  { additionalProperties: false },
+)

package/src/usecases/add-memory/types.ts

@@ -0,0 +1,47 @@
+import type { Static } from "typebox"
+
+import type {
+  ConfigRefusal,
+  CreateResult,
+  MemoryScope,
+  NoProjectRefusal,
+  PathPlatform,
+  StoredNote,
+} from "#src/services"
+import type { Failed, Succeeded } from "#src/shared"
+import type { MemoryOperationRefusal } from "#src/usecases/operation-context"
+import type { AddMemoryRequestSchema } from "./schemas.ts"
+
+export type AddMemoryRequest = Static<typeof AddMemoryRequestSchema>
+
+export interface MemoryContext {
+  configPath: string
+  workingFolder: string
+  platform: PathPlatform
+}
+
+export interface AddedMemory {
+  scope: MemoryScope
+  vaultName: string
+  folder: string
+  notePath: string
+  stored: StoredNote
+  maintenanceProblems: string[]
+}
+
+export interface UnregisteredProjectRefusal extends NoProjectRefusal {
+  configPath: string
+}
+
+export interface ExistingMemoryRefusal extends Failed {
+  reason: "exists"
+  existing: StoredNote
+}
+
+export type AddMemoryResult =
+  | Succeeded<AddedMemory>
+  | ConfigRefusal
+  | UnregisteredProjectRefusal
+  | Extract<CreateResult, Failed>
+  | ExistingMemoryRefusal
+  | MemoryOperationRefusal