pi-obsidian-memory 0.0.1 → 0.1.1

package/src/services/shell-scripts/files.ts

@@ -0,0 +1,16 @@
+import { readFile } from "node:fs/promises"
+
+import type { ScriptTextResult } from "./types.ts"
+
+export function isAbsentError(error: Error): boolean {
+  return "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")
+}
+
+export async function readScriptText(path: string): Promise<ScriptTextResult> {
+  try {
+    return { succeeded: true, output: await readFile(path, "utf8") }
+  } catch (error) {
+    if (error instanceof Error && isAbsentError(error)) return { succeeded: false }
+    return { succeeded: false, problems: [`${path} cannot be read: ${String(error)}`] }
+  }
+}

package/src/services/shell-scripts/index.ts

@@ -0,0 +1,5 @@
+export * from "./constants.ts"
+export * from "./files.ts"
+export * from "./package-scripts.ts"
+export * from "./scripts.ts"
+export * from "./types.ts"

package/src/services/shell-scripts/package-scripts.ts

@@ -0,0 +1,74 @@
+import { stat } from "node:fs/promises"
+import { dirname, join, resolve } from "node:path"
+
+import { Value } from "typebox/value"
+
+import { PACKAGE_SCRIPT_PREFIX } from "./constants.ts"
+import { isAbsentError, readScriptText } from "./files.ts"
+import { PackageScriptsSchema } from "./schemas.ts"
+import type { ExecutedScriptsResult, ScriptLinesResult } from "./types.ts"
+
+async function nearestPackageJson(cwd: string): Promise<string> {
+  for (let folder = resolve(cwd); ; folder = dirname(folder)) {
+    const candidate = join(folder, "package.json")
+    try {
+      await stat(candidate)
+      return candidate
+    } catch (error) {
+      if (!(error instanceof Error && isAbsentError(error))) throw error
+    }
+    if (dirname(folder) === folder) return ""
+  }
+}
+
+async function packageJsonFor(cwd: string, prefix: string): Promise<string> {
+  if (prefix === "") return nearestPackageJson(cwd)
+  return join(resolve(cwd, prefix), "package.json")
+}
+
+function scriptLabel(prefix: string, name: string): string {
+  if (prefix === "") return PACKAGE_SCRIPT_PREFIX + name
+  return `${prefix}/${PACKAGE_SCRIPT_PREFIX}${name}`
+}
+
+function scriptLines(path: string, text: string): ScriptLinesResult {
+  try {
+    const parsed = JSON.parse(text)
+    if (!Value.Check(PackageScriptsSchema, parsed)) {
+      return { succeeded: false, problems: [`${path}: "scripts" must map names to text`] }
+    }
+    if (!parsed.scripts) return { succeeded: true, output: new Map() }
+    return { succeeded: true, output: new Map(Object.entries(parsed.scripts)) }
+  } catch (error) {
+    return { succeeded: false, problems: [`${path} is not valid JSON: ${String(error)}`] }
+  }
+}
+
+export async function readPackageScripts(cwd: string, prefix: string, names: string[]): Promise<ExecutedScriptsResult> {
+  const label = (name: string) => scriptLabel(prefix, name)
+  const labels = names.map(label)
+  if (names.length === 0) return { succeeded: true, output: { scripts: [], missing: [] } }
+  try {
+    const path = await packageJsonFor(cwd, prefix)
+    if (path === "") return { succeeded: true, output: { scripts: [], missing: labels } }
+    const read = await readScriptText(path)
+    if (!read.succeeded) {
+      if ("problems" in read) return read
+      return { succeeded: true, output: { scripts: [], missing: labels } }
+    }
+    const lines = scriptLines(path, read.output)
+    if (!lines.succeeded) return lines
+    const scripts = names.flatMap((name) => {
+      const text = lines.output.get(name)
+      if (typeof text === "string") return [{ path: label(name), text }]
+      return []
+    })
+    const missing = names.filter((name) => !lines.output.has(name)).map(label)
+    return { succeeded: true, output: { scripts, missing } }
+  } catch (error) {
+    return {
+      succeeded: false,
+      problems: [`package.json above ${resolve(cwd)} cannot be found or read: ${String(error)}`],
+    }
+  }
+}

package/src/services/shell-scripts/schemas.ts

@@ -0,0 +1,3 @@
+import Type from "typebox"
+
+export const PackageScriptsSchema = Type.Object({ scripts: Type.Optional(Type.Record(Type.String(), Type.String())) })

package/src/services/shell-scripts/scripts.ts

@@ -0,0 +1,27 @@
+import { resolve } from "node:path"
+
+import type { ExecutedFile, ShellEditScript } from "#src/domain"
+import { readScriptText } from "./files.ts"
+import { readPackageScripts } from "./package-scripts.ts"
+import type { ExecutedScriptsResult } from "./types.ts"
+
+export async function readExecutedScripts(cwd: string, files: ExecutedFile[]): Promise<ExecutedScriptsResult> {
+  const scripts: ShellEditScript[] = []
+  const missing: string[] = []
+  for (const file of files) {
+    if (file.kind !== "script") continue
+    const read = await readScriptText(resolve(cwd, file.path))
+    if (read.succeeded) scripts.push({ path: file.path, text: read.output })
+    else if ("problems" in read) return read
+    else missing.push(file.path)
+  }
+  const packages = files.filter((file) => file.kind === "package-script")
+  for (const prefix of new Set(packages.map((file) => file.prefix))) {
+    const names = packages.filter((file) => file.prefix === prefix).map((file) => file.name)
+    const packaged = await readPackageScripts(cwd, prefix, names)
+    if (!packaged.succeeded) return packaged
+    scripts.push(...packaged.output.scripts)
+    missing.push(...packaged.output.missing)
+  }
+  return { succeeded: true, output: { scripts, missing } }
+}

package/src/services/shell-scripts/types.ts

@@ -0,0 +1,11 @@
+import type { ShellEditScript } from "#src/domain"
+import type { Absent, Failed, Succeeded } from "#src/shared"
+
+export interface ExecutedScripts {
+  scripts: ShellEditScript[]
+  missing: string[]
+}
+
+export type ScriptTextResult = Succeeded<string> | Absent | Failed
+export type ExecutedScriptsResult = Succeeded<ExecutedScripts> | Failed
+export type ScriptLinesResult = Succeeded<Map<string, string>> | Failed

package/src/services/vault/archive.ts

@@ -0,0 +1,31 @@
+import { archiveNote } from "#src/domain"
+import type { NamedVaultContext } from "#src/services/vault/context"
+import { relocateNote } from "./relocate.ts"
+import type { ArchiveRequest, ExactArchiveRequest, PlacedResult } from "./types.ts"
+
+export async function archiveStoredNote(vault: NamedVaultContext, request: ArchiveRequest): Promise<PlacedResult> {
+  return archiveOriginal(vault, request, null)
+}
+
+export async function archiveStoredFile(vault: NamedVaultContext, request: ExactArchiveRequest): Promise<PlacedResult> {
+  return archiveOriginal(vault, request, request.path)
+}
+
+async function archiveOriginal(
+  vault: NamedVaultContext,
+  request: ArchiveRequest,
+  originalPath: string | null,
+): Promise<PlacedResult> {
+  const archived = archiveNote(request.note, request.today)
+  const relocated = await relocateNote(vault, {
+    original: request.note,
+    originalPath,
+    hashWhenRead: request.hashWhenRead,
+    written: [archived],
+  })
+  if (!relocated.succeeded) {
+    return relocated
+  }
+
+  return { ...relocated, output: archived }
+}

package/src/services/vault/bootstrap/ensure.ts

@@ -0,0 +1,50 @@
+import { mkdir } from "node:fs/promises"
+
+import {
+  renderVaultAssets,
+  type VaultBootstrapProgress,
+  type VaultBootstrapResult,
+  type VaultCatalogFailure,
+} from "#src/domain"
+import { catalogIoFailure, resolveCatalogRoot } from "#src/services/vault/catalog"
+import type { NamedVaultContext } from "#src/services/vault/context"
+import { ensureTemplateFolder } from "./paths.ts"
+import { createAssetExclusively } from "./write.ts"
+
+export async function ensureVaultAssets(vault: NamedVaultContext): Promise<VaultBootstrapResult> {
+  const progress: VaultBootstrapProgress = { createdRoot: false, created: [], preserved: [], maintenanceProblems: [] }
+  try {
+    const created = await mkdir(vault.path, { recursive: true })
+    progress.createdRoot = typeof created === "string"
+  } catch (error) {
+    if (!(error instanceof Error)) throw error
+    return bootstrapFailure(progress, catalogIoFailure(error, { path: "", scope: "directory" }))
+  }
+  const root = await resolveCatalogRoot(vault)
+  if (!root.succeeded) return bootstrapFailure(progress, root)
+  const templates = await ensureTemplateFolder(root.output)
+  if (!templates.succeeded) return bootstrapFailure(progress, templates)
+  return installAssets(root.output, templates.output, progress)
+}
+
+async function installAssets(
+  root: string,
+  templates: string,
+  progress: VaultBootstrapProgress,
+): Promise<VaultBootstrapResult> {
+  for (const asset of renderVaultAssets()) {
+    let folder = ""
+    let name = asset.path
+    if (asset.path.startsWith("_templates/")) {
+      folder = templates
+      name = asset.path.slice("_templates/".length)
+    }
+    const written = await createAssetExclusively({ root, folder, name, content: asset.content, progress })
+    if (!written.succeeded) return bootstrapFailure(progress, written)
+  }
+  return { succeeded: true, output: progress }
+}
+
+function bootstrapFailure(progress: VaultBootstrapProgress, failure: VaultCatalogFailure): VaultBootstrapResult {
+  return { succeeded: false, ...progress, failure, problems: failure.problems }
+}

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

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

package/src/services/vault/bootstrap/paths.ts

@@ -0,0 +1,57 @@
+import { mkdir, readdir } from "node:fs/promises"
+import { join } from "node:path"
+
+import { catalogFailure, catalogIoFailure, resolveCatalogEntry } from "#src/services/vault/catalog"
+import type { AssetLocation, AssetPathResult } from "./types.ts"
+
+export async function existingAsset(location: AssetLocation): Promise<AssetPathResult> {
+  const folder = await resolveCatalogEntry({ root: location.root, path: location.folder })
+  if (!folder.succeeded) return folder
+  try {
+    const names = await readdir(folder.output.absolutePath)
+    const matches = names.filter((name) => name.toLowerCase() === location.name.toLowerCase())
+    if (matches.length > 1) {
+      return catalogFailure({
+        path: location.folder,
+        scope: "entry",
+        reason: "invalid-path",
+        problem: `Ambiguous asset name: ${location.name}`,
+      })
+    }
+    const name = matches[0]
+    if (!name) return { succeeded: true, output: "" }
+    return { succeeded: true, output: [location.folder, name].filter((part) => part !== "").join("/") }
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path: location.folder, scope: "directory" })
+    throw error
+  }
+}
+
+export async function ensureTemplateFolder(root: string): Promise<AssetPathResult> {
+  const existing = await existingAsset({ root, folder: "", name: "_templates" })
+  if (!existing.succeeded) return existing
+  if (existing.output !== "") return checkedDirectory(root, existing.output)
+  try {
+    await mkdir(join(root, "_templates"))
+  } catch (error) {
+    if (!(error instanceof Error)) throw error
+    if (!("code" in error) || error.code !== "EEXIST") {
+      return catalogIoFailure(error, { path: "_templates", scope: "directory" })
+    }
+  }
+  return checkedDirectory(root, "_templates")
+}
+
+async function checkedDirectory(root: string, path: string): Promise<AssetPathResult> {
+  const resolved = await resolveCatalogEntry({ root, path })
+  if (!resolved.succeeded) return resolved
+  if (resolved.output.kind !== "directory") {
+    return catalogFailure({
+      path,
+      scope: "directory",
+      reason: "not-directory",
+      problem: "Templates must be a directory",
+    })
+  }
+  return { succeeded: true, output: path }
+}

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

@@ -0,0 +1,17 @@
+import type { VaultBootstrapProgress, VaultCatalogFailure } from "#src/domain"
+import type { Succeeded } from "#src/shared"
+
+export type { VaultBootstrapFailure, VaultBootstrapProgress, VaultBootstrapResult } from "#src/domain"
+
+export interface AssetLocation {
+  root: string
+  folder: string
+  name: string
+}
+
+export interface AssetWriteRequest extends AssetLocation {
+  content: string
+  progress: VaultBootstrapProgress
+}
+
+export type AssetPathResult = Succeeded<string> | VaultCatalogFailure

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

@@ -0,0 +1,47 @@
+import { join } from "node:path"
+
+import type { VaultCatalogFailure } from "#src/domain"
+import { catalogFailure, catalogIoFailure, resolveCatalogEntry } from "#src/services/vault/catalog"
+import { publishExclusively } from "#src/services/vault/filesystem"
+import type { Done } from "#src/shared"
+import { existingAsset } from "./paths.ts"
+import type { AssetWriteRequest } from "./types.ts"
+
+export async function createAssetExclusively(request: AssetWriteRequest): Promise<Done | VaultCatalogFailure> {
+  const existing = await existingAsset(request)
+  if (!existing.succeeded) return existing
+  if (existing.output !== "") return preserveAsset(request, existing.output)
+  const parent = await resolveCatalogEntry({ root: request.root, path: request.folder })
+  if (!parent.succeeded) return parent
+  return publishAsset(request, parent.output.absolutePath)
+}
+
+async function publishAsset(request: AssetWriteRequest, parent: string): Promise<Done | VaultCatalogFailure> {
+  const path = [request.folder, request.name].filter((part) => part !== "").join("/")
+  try {
+    const written = await publishExclusively(join(parent, request.name), request.content)
+    if (!written.succeeded) {
+      if (written.reason !== "exists") {
+        return { succeeded: false, path, scope: "file", reason: "not-writable", problems: written.problems }
+      }
+      request.progress.maintenanceProblems.push(...written.problems)
+      return preserveAsset(request, path)
+    }
+    if (written.maintenanceProblems) request.progress.maintenanceProblems.push(...written.maintenanceProblems)
+    request.progress.created.push(path)
+    return { succeeded: true }
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path, scope: "file" })
+    throw error
+  }
+}
+
+async function preserveAsset(request: AssetWriteRequest, path: string): Promise<Done | VaultCatalogFailure> {
+  const resolved = await resolveCatalogEntry({ root: request.root, path })
+  if (!resolved.succeeded) return resolved
+  if (resolved.output.kind !== "file") {
+    return catalogFailure({ path, scope: "file", reason: "not-file", problem: "The asset path is not a regular file" })
+  }
+  request.progress.preserved.push(path)
+  return { succeeded: true }
+}

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

@@ -0,0 +1,51 @@
+import { open, stat } from "node:fs/promises"
+
+import type { VaultCatalogFailure } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { hashOf } from "#src/services/vault/filesystem"
+import { catalogFailure, catalogIoFailure } from "./failures.ts"
+import { resolveCatalogEntry, resolveCatalogRoot } from "./resolve.ts"
+import { catalogStat, sameCatalogStat } from "./stat.ts"
+import type { CatalogBytesResult, CatalogReadRequest, ResolvedCatalogEntry } from "./types.ts"
+
+export async function readCatalogBytes(vault: VaultContext, request: CatalogReadRequest): Promise<CatalogBytesResult> {
+  const root = await resolveCatalogRoot(vault)
+  if (!root.succeeded) return root
+  const resolved = await resolveCatalogEntry({ root: root.output, path: request.path })
+  if (!resolved.succeeded) return resolved
+  if (resolved.output.kind !== "file") {
+    return catalogFailure({ path: request.path, scope: "file", reason: "not-file", problem: "Expected a regular file" })
+  }
+  try {
+    return await readStableBytes(resolved.output, request)
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path: request.path, scope: "file" })
+    throw error
+  }
+}
+
+async function readStableBytes(entry: ResolvedCatalogEntry, request: CatalogReadRequest): Promise<CatalogBytesResult> {
+  const before = entry.stat
+  if (request.expectedStat && !sameCatalogStat(before, request.expectedStat)) return changed(request.path)
+  const file = await open(entry.absolutePath, "r")
+  try {
+    const opened = catalogStat(await file.stat())
+    if (!sameCatalogStat(before, opened)) return changed(request.path)
+    const bytes = await file.readFile()
+    const after = catalogStat(await file.stat())
+    if (!sameCatalogStat(before, after)) return changed(request.path)
+    if (!sameCatalogStat(after, catalogStat(await stat(entry.absolutePath)))) return changed(request.path)
+    return { succeeded: true, output: { path: request.path, bytes, rawHash: hashOf(bytes), stat: after } }
+  } finally {
+    await file.close()
+  }
+}
+
+function changed(path: string): VaultCatalogFailure {
+  return catalogFailure({
+    path,
+    scope: "file",
+    reason: "changed",
+    problem: "The file changed while collecting its snapshot",
+  })
+}

package/src/services/vault/catalog/dont-forget.ts

@@ -0,0 +1 @@
+export { isLoadedDontForget } from "#src/domain"

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

@@ -0,0 +1,69 @@
+import type { Dirent } from "node:fs"
+import { readdir } from "node:fs/promises"
+
+import { catalogFileKind, isCatalogHidden, isCatalogNotePath, type VaultEnumerationResult } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { catalogIoFailure } from "./failures.ts"
+import { resolveCatalogEntry, resolveCatalogRoot, resolveListedEntry } from "./resolve.ts"
+import type { CatalogResolveResult, CatalogWalk, CatalogWalkRequest } from "./types.ts"
+import { visitCatalogEntry } from "./visit.ts"
+
+export async function enumerateVault(vault: VaultContext): Promise<VaultEnumerationResult> {
+  return walkVault({ vault, mode: "memory" })
+}
+
+export async function walkVault(request: CatalogWalkRequest): Promise<VaultEnumerationResult> {
+  const root = await resolveCatalogRoot(request.vault)
+  if (!root.succeeded) return root
+  const walk: CatalogWalk = {
+    ...request,
+    root: root.output,
+    pending: [""],
+    inventory: { entries: [], observedPaths: [], completeDirectories: [], failures: [], aliases: [] },
+  }
+  while (walk.pending.length > 0) {
+    const folder = walk.pending.pop()
+    if (typeof folder === "string") await enumerateDirectory(walk, folder)
+  }
+  walk.inventory.entries.sort((a, b) => a.path.localeCompare(b.path))
+  return { succeeded: true, output: walk.inventory }
+}
+
+async function enumerateDirectory(walk: CatalogWalk, folder: string): Promise<void> {
+  const resolved = await resolveCatalogEntry({ root: walk.root, path: folder })
+  if (!resolved.succeeded) {
+    walk.inventory.failures.push({ ...resolved, scope: "directory" })
+    return
+  }
+  try {
+    const canonicalFolder = resolved.output.canonicalPath === folder
+    const entries = await readdir(resolved.output.absolutePath, { withFileTypes: true })
+    walk.inventory.completeDirectories.push(folder)
+    for (const entry of entries) {
+      const path = [folder, entry.name].filter((part) => part !== "").join("/")
+      if (skipEntry(walk, path, entry.isDirectory())) continue
+      walk.inventory.observedPaths.push(path)
+      visitCatalogEntry(walk, path, await resolveListing(walk, path, entry, canonicalFolder))
+    }
+  } catch (error) {
+    if (!(error instanceof Error)) throw error
+    walk.inventory.failures.push(catalogIoFailure(error, { path: folder, scope: "directory" }))
+  }
+}
+
+async function resolveListing(
+  walk: CatalogWalk,
+  path: string,
+  entry: Dirent,
+  canonicalFolder: boolean,
+): Promise<CatalogResolveResult> {
+  const location = { root: walk.root, path }
+  if (canonicalFolder) return resolveListedEntry(location, entry)
+  return resolveCatalogEntry(location)
+}
+
+function skipEntry(walk: CatalogWalk, path: string, directory: boolean): boolean {
+  if (walk.mode === "export") return isCatalogHidden(path) || catalogFileKind(path) === "temporary"
+  if (directory) return isCatalogHidden(path)
+  return isCatalogHidden(path) && !isCatalogNotePath(path) && catalogFileKind(path) !== "temporary"
+}

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

@@ -0,0 +1,21 @@
+import type { VaultCatalogFailure, VaultExportFile, VaultExportResult } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { readCatalogBytes } from "./bytes.ts"
+import { walkVault } from "./enumerate.ts"
+
+export async function collectExportFiles(vault: VaultContext): Promise<VaultExportResult> {
+  const scan = await walkVault({ vault, mode: "export" })
+  if (!scan.succeeded) return { succeeded: false, failures: [scan], problems: scan.problems }
+  const failures: VaultCatalogFailure[] = [...scan.output.failures]
+  const files: VaultExportFile[] = []
+  for (const entry of scan.output.entries) {
+    if (entry.kind === "folder" || entry.kind === "temporary") continue
+    const read = await readCatalogBytes(vault, { path: entry.path, expectedStat: entry.stat })
+    if (read.succeeded) files.push(read.output)
+    else failures.push(read)
+  }
+  if (failures.length > 0) {
+    return { succeeded: false, failures, problems: failures.flatMap((failure) => failure.problems) }
+  }
+  return { succeeded: true, output: files }
+}

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

@@ -0,0 +1,16 @@
+import type { VaultCatalogFailure } from "#src/domain"
+import type { CatalogFailureDetail, CatalogOperation } from "./types.ts"
+
+export function catalogFailure(detail: CatalogFailureDetail): VaultCatalogFailure {
+  return { succeeded: false, path: detail.path, scope: detail.scope, reason: detail.reason, problems: [detail.problem] }
+}
+
+export function catalogIoFailure(error: Error, operation: CatalogOperation): VaultCatalogFailure {
+  let reason: VaultCatalogFailure["reason"] = "io-error"
+  if ("code" in error) {
+    if (error.code === "ENOENT") reason = "not-found"
+    if (error.code === "ENOTDIR") reason = "not-directory"
+    if (error.code === "EACCES" || error.code === "EPERM" || error.code === "EBUSY") reason = "unreadable"
+  }
+  return catalogFailure({ ...operation, reason, problem: error.message })
+}

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

@@ -0,0 +1,10 @@
+export * from "./bytes.ts"
+export * from "./dont-forget.ts"
+export * from "./enumerate.ts"
+export * from "./export.ts"
+export * from "./failures.ts"
+export * from "./inspect.ts"
+export * from "./observe.ts"
+export * from "./resolve.ts"
+export * from "./stat.ts"
+export * from "./types.ts"

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

@@ -0,0 +1,41 @@
+import {
+  analyzeVaultNote,
+  type InspectedVaultFile,
+  isCatalogNotePath,
+  isRootArchive,
+  type VaultExportFile,
+  type VaultFileRequest,
+  type VaultInspectionResult,
+} from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { readCatalogBytes } from "./bytes.ts"
+import { catalogFailure } from "./failures.ts"
+import { resolveCatalogEntry, resolveCatalogRoot } from "./resolve.ts"
+
+export async function inspectVaultFile(vault: VaultContext, request: VaultFileRequest): Promise<VaultInspectionResult> {
+  const root = await resolveCatalogRoot(vault)
+  if (!root.succeeded) return root
+  const resolved = await resolveCatalogEntry({ root: root.output, path: request.path })
+  if (!resolved.succeeded) return resolved
+  const canonicalPath = resolved.output.canonicalPath
+  if (resolved.output.kind !== "file" || ![request.path, canonicalPath].every(isCatalogNotePath)) {
+    return catalogFailure({
+      path: request.path,
+      scope: "file",
+      reason: "excluded",
+      problem: "This path is not a memory note",
+    })
+  }
+
+  const raw = await readCatalogBytes(vault, { ...request, expectedStat: resolved.output.stat })
+  if (!raw.succeeded) return raw
+  return { succeeded: true, output: inspectContent(vault, raw.output, canonicalPath) }
+}
+
+function inspectContent(vault: VaultContext, raw: VaultExportFile, canonicalPath: string): InspectedVaultFile {
+  const text = Buffer.from(raw.bytes).toString("utf8")
+  const archived = isRootArchive(raw.path) || isRootArchive(canonicalPath)
+  const statement = canonicalPath.slice(canonicalPath.lastIndexOf("/") + 1, -3)
+  const analysis = analyzeVaultNote({ statement, text, archived, limits: vault.limits })
+  return { path: raw.path, canonicalPath, text, rawHash: raw.rawHash, stat: raw.stat, archived, analysis }
+}

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

@@ -0,0 +1,35 @@
+import { isCatalogHidden, isRootTemplate, type VaultFileRequest } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { catalogFailure } from "./failures.ts"
+import { resolveCatalogEntry, resolveCatalogRoot } from "./resolve.ts"
+import type { CatalogResolveResult } from "./types.ts"
+
+export async function observeVaultPath(vault: VaultContext, request: VaultFileRequest): Promise<CatalogResolveResult> {
+  let path = request.path
+  if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1)
+  const root = await resolveCatalogRoot(vault)
+  if (!root.succeeded) return root
+  const entry = await resolveCatalogEntry({ root: root.output, path })
+  if (!entry.succeeded) return entry
+  if (request.path.endsWith("/") && entry.output.kind !== "directory") {
+    return catalogFailure({
+      path: request.path,
+      scope: "directory",
+      reason: "not-directory",
+      problem: "Expected a folder",
+    })
+  }
+  if (entry.output.kind === "directory" && ![path, entry.output.canonicalPath].every(isReadableFolder)) {
+    return catalogFailure({
+      path: request.path,
+      scope: "directory",
+      reason: "excluded",
+      problem: "This folder is not readable memory",
+    })
+  }
+  return entry
+}
+
+function isReadableFolder(path: string): boolean {
+  return !isCatalogHidden(path) && !isRootTemplate(path)
+}