pi-obsidian-memory 0.0.0 → 0.1.0

package/src/domain/vault-access/constants.ts

@@ -0,0 +1,54 @@
+export const VAULT_ACCESS_REFUSAL =
+  "Vault files are reachable only through memory_search and memory_get, never with file tools or the shell."
+
+export const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g
+
+export const WINDOWS_SHELL_DRIVE_PREFIX = /^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/|$)/i
+
+export const NAMESPACE_UNC_PREFIX = /^\\\\[?.]\\UNC\\/i
+
+export const TRAILING_NAMESPACE_SEPARATOR = /^(\\\\[?.]\\.+)\\$/
+
+export const FILE_URL_PREFIX = /(?<=^|[\s=(,;|&<>])file:\/\//g
+
+export const WINDOWS_FILE_URL_PREFIX = /(?<=^|[\s=(,;|&<>])file:\/\/\/(?=[a-z]:)/gi
+
+export const NAMESPACE_PREFIX = /^\\\\[?.]\\/
+
+export const LOCAL_ADMIN_SHARE = /^\\\\(?:localhost|127\.0\.0\.1)\\([a-z])\$(?:\\|$)/i
+
+export const DRIVE_OR_UNC_START = /^(?:[a-z]:|\\\\)/i
+
+export const COMPARABLE_NAMESPACE_UNC = /(?<=^|[\s=(,;|&<>])\/\/[?.]\/unc\//g
+
+export const COMPARABLE_NAMESPACE = /(?<=^|[\s=(,;|&<>])\/\/[?.]\//g
+
+export const COMPARABLE_ADMIN_SHARE = /(?<=^|[\s=(,;|&<>])\/\/(?:localhost|127\.0\.0\.1)\/([a-z])\$(?=\/|$)/g
+
+export const PATH_TOKEN_START = /(?:^|[\s=(,;|&<>])$/
+
+export const PATH_TOKEN_END = /^(?:$|[\s/|;&)<>,]|\.(?:$|[\s/]))/
+
+export const PATH_FOLLOWS = /^\.?\//
+
+export const QUOTE_CHARACTERS = ['"', "'", "`"]
+
+export const TOKEN_SEPARATOR = /[\s=|;&()<>,]/
+
+export const WINDOWS_DRIVE_START = /^[a-z]:\//
+
+export const DRIVE_PATH_PREFIXES = ["/", "/mnt/", "/cygdrive/"]
+
+export const VARIABLE_REFERENCE = /\$(?:env:)?\{?\w+\}?|%\w+%/gi
+
+export const PARENT_FOLDER_START = /^\.\.(\/|$)/
+
+export const HOME_PREFIXES = [
+  "~/",
+  "$home/",
+  "\u0024{home}/",
+  "$env:home/",
+  "%userprofile%/",
+  "$env:userprofile/",
+  "%homedrive%%homepath%/",
+]

package/src/domain/vault-access/index.ts

@@ -0,0 +1,7 @@
+export * from "./absolute-candidate.ts"
+export * from "./argument-tokens.ts"
+export * from "./command-mentions-vault.ts"
+export * from "./constants.ts"
+export * from "./types.ts"
+export * from "./vault-access-refusal.ts"
+export * from "./vault-location.ts"

package/src/domain/vault-access/types.ts

@@ -0,0 +1,18 @@
+export type PathAccessKind = "file" | "tree" | "listing"
+
+export interface PathAccessRequest {
+  kind: PathAccessKind
+  path: string
+}
+
+export interface CommandAccessRequest {
+  kind: "command"
+  command: string
+}
+
+export type VaultAccessRequest = PathAccessRequest | CommandAccessRequest
+
+export interface VaultForms {
+  anywhere: string[]
+  relative: string[]
+}

package/src/domain/vault-access/vault-access-refusal.ts

@@ -0,0 +1,36 @@
+import type { PathPlatform } from "#src/domain/path-platform"
+import { absoluteCandidate } from "./absolute-candidate.ts"
+import { commandMentionsVault } from "./command-mentions-vault.ts"
+import type { PathAccessRequest, VaultAccessRequest } from "./types.ts"
+import { vaultBelow, vaultContaining } from "./vault-location.ts"
+
+export function vaultAccessRefusal(
+  request: VaultAccessRequest,
+  cwd: string,
+  home: string,
+  vaults: string[],
+  platform: PathPlatform,
+): string | null {
+  if (request.kind === "command") {
+    return commandMentionsVault(request.command, cwd, home, vaults, platform)
+  }
+
+  return pathVaultHit(request, absoluteCandidate(request.path, cwd, home, platform), vaults, platform)
+}
+
+function pathVaultHit(
+  request: PathAccessRequest,
+  path: string,
+  vaults: string[],
+  platform: PathPlatform,
+): string | null {
+  const containing = vaultContaining(path, vaults, platform)
+  if (containing) {
+    return containing
+  }
+  if (request.kind === "tree") {
+    return vaultBelow(path, vaults, platform)
+  }
+
+  return null
+}

package/src/domain/vault-access/vault-location.ts

@@ -0,0 +1,22 @@
+import { isInside } from "#src/domain/config"
+import type { PathPlatform } from "#src/domain/path-platform"
+
+export function vaultContaining(path: string, vaults: string[], platform: PathPlatform): string | null {
+  for (const vault of vaults) {
+    if (isInside(path, vault, platform)) {
+      return vault
+    }
+  }
+
+  return null
+}
+
+export function vaultBelow(path: string, vaults: string[], platform: PathPlatform): string | null {
+  for (const vault of vaults) {
+    if (isInside(vault, path, platform)) {
+      return vault
+    }
+  }
+
+  return null
+}

package/src/domain/vault-assets/index.ts

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

package/src/domain/vault-assets/render.ts

@@ -0,0 +1,51 @@
+import { stringify } from "yaml"
+
+import { type NoteType, NoteTypeSchema } from "#src/domain/note"
+import type { DashboardView, VaultAsset, VaultDashboard } from "./types.ts"
+
+export function renderVaultAssets(): VaultAsset[] {
+  return [...NoteTypeSchema.enum.map(renderHandTemplate), { path: "Memory.base", content: stringify(dashboard()) }]
+}
+
+function renderHandTemplate(type: NoteType): VaultAsset {
+  return {
+    path: `_templates/${type}.md`,
+    content: [
+      "---",
+      "id: REPLACE_WITH_NEW_ULID",
+      `type: ${type}`,
+      'created: "{{date:YYYY-MM-DD}}"',
+      'updated: "{{date:YYYY-MM-DD}}"',
+      "---",
+      "",
+      "{{title}}",
+      "",
+    ].join("\n"),
+  }
+}
+
+function dashboard(): VaultDashboard {
+  return {
+    filters: {
+      and: [
+        'file.ext.lower() == "md"',
+        'file.basename.lower() != "index"',
+        '!file.path.lower().startsWith("_templates/")',
+      ],
+    },
+    views: [
+      view("All notes", ['!file.path.lower().startsWith("archive/")']),
+      view("Don't forget", ['!file.path.lower().startsWith("archive/")', "note.dontForget == true"]),
+      view("Archive", ['file.path.lower().startsWith("archive/")']),
+    ],
+  }
+}
+
+function view(name: string, filters: string[]): DashboardView {
+  return {
+    type: "table",
+    name,
+    filters: { and: filters },
+    order: ["file.name", "file.folder", "note.type", "note.dontForget", "note.updated"],
+  }
+}

package/src/domain/vault-assets/types.ts

@@ -0,0 +1,36 @@
+import type { VaultCatalogFailure } from "#src/domain/vault-catalog"
+import type { Failed, Succeeded } from "#src/shared"
+
+export interface VaultAsset {
+  path: string
+  content: string
+}
+
+export interface DashboardFilters {
+  and: string[]
+}
+
+export interface DashboardView {
+  type: "table"
+  name: string
+  filters: DashboardFilters
+  order: string[]
+}
+
+export interface VaultDashboard {
+  filters: DashboardFilters
+  views: DashboardView[]
+}
+
+export interface VaultBootstrapProgress {
+  createdRoot: boolean
+  created: string[]
+  preserved: string[]
+  maintenanceProblems: string[]
+}
+
+export interface VaultBootstrapFailure extends Failed, VaultBootstrapProgress {
+  failure: VaultCatalogFailure
+}
+
+export type VaultBootstrapResult = Succeeded<VaultBootstrapProgress> | VaultBootstrapFailure

package/src/domain/vault-catalog/analyze.ts

@@ -0,0 +1,37 @@
+import { checkNoteText, parseNote, readFrontmatter } from "#src/domain/note"
+import type { AnalyzeVaultNoteRequest, ParsedVaultNote, VaultNoteAnalysis, VaultNoteProblems } from "./types.ts"
+
+export function analyzeVaultNote(request: AnalyzeVaultNoteRequest): VaultNoteAnalysis {
+  const parsed = parseNote(request.statement, request.text)
+  if (!parsed.succeeded) {
+    const text = textProblems(request, request.text)
+    return { status: "unclosed", searchable: false, needsFixing: true, ...text, frontmatterProblems: parsed.problems }
+  }
+
+  const result: ParsedVaultNote = {
+    status: "parsed",
+    parsed: parsed.output,
+    frontmatter: null,
+    searchable: false,
+    needsFixing: true,
+    ...textProblems(request, parsed.output.body),
+  }
+  const frontmatter = readFrontmatter(parsed.output.frontmatter)
+  if (!frontmatter.succeeded) return { ...result, frontmatterProblems: frontmatter.problems }
+
+  return {
+    ...result,
+    frontmatter: frontmatter.output,
+    searchable: !request.archived && !("archived" in frontmatter.output),
+    needsFixing: result.nameProblems.length + result.bodyProblems.length > 0,
+  }
+}
+
+function textProblems(request: AnalyzeVaultNoteRequest, body: string): VaultNoteProblems {
+  const problems = checkNoteText(request.statement, body, request.limits)
+  return {
+    frontmatterProblems: [],
+    nameProblems: problems.filter((problem) => problem.startsWith("statement:")),
+    bodyProblems: problems.filter((problem) => problem.startsWith("body:")),
+  }
+}

package/src/domain/vault-catalog/classify.ts

@@ -0,0 +1,37 @@
+import type { VaultEntryKind } from "./types.ts"
+
+export function isRootArchive(path: string): boolean {
+  return path.split("/")[0]?.toLowerCase() === "archive"
+}
+
+export function isRootTemplate(path: string): boolean {
+  return path.split("/")[0]?.toLowerCase() === "_templates"
+}
+
+export function isCatalogHidden(path: string): boolean {
+  return path.split("/").some((part) => part.startsWith("."))
+}
+
+export function catalogFileKind(path: string): Exclude<VaultEntryKind, "folder"> {
+  const lower = path.toLowerCase()
+  const name = lower.split("/").at(-1)
+  if (/\.md\.tmp-[^/]+$/i.test(path) || /^\.memory\.base\.tmp-[^/]+$/.test(lower)) return "temporary"
+  if (isRootTemplate(path)) return "template"
+  if (name === "index.md") return "index"
+  if (lower === "memory.base") return "dashboard"
+  if (lower.endsWith(".md")) return "note"
+  return "other"
+}
+
+export function isCatalogNotePath(path: string): boolean {
+  const parent = path.slice(0, path.lastIndexOf("/") + 1)
+  return !isCatalogHidden(parent) && catalogFileKind(path) === "note"
+}
+
+export function isSafeCatalogPath(path: string): boolean {
+  return path.length > 0 && path.split("/").every(isSafeCatalogPart)
+}
+
+function isSafeCatalogPart(part: string): boolean {
+  return part.length > 0 && part !== "." && part !== ".." && !/[\\:]/.test(part) && !part.includes("\u0000")
+}

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

@@ -0,0 +1,6 @@
+import type { VaultNoteAnalysis } from "./types.ts"
+
+export function isLoadedDontForget(analysis: VaultNoteAnalysis): boolean {
+  if (analysis.status !== "parsed" || !analysis.frontmatter) return false
+  return analysis.searchable && "dontForget" in analysis.frontmatter
+}

package/src/domain/vault-catalog/export-entries.ts

@@ -0,0 +1,10 @@
+import type { VaultExportEntry, VaultExportFile } from "./types.ts"
+
+export function exportEntries(
+  global: readonly VaultExportFile[],
+  project: readonly VaultExportFile[] | null,
+): VaultExportEntry[] {
+  const entries = global.map((file) => ({ path: `global/${file.path}`, bytes: file.bytes }))
+  if (!project) return entries
+  return [...entries, ...project.map((file) => ({ path: `project/${file.path}`, bytes: file.bytes }))]
+}

package/src/domain/vault-catalog/index.ts

@@ -0,0 +1,5 @@
+export * from "./analyze.ts"
+export * from "./classify.ts"
+export * from "./dont-forget.ts"
+export * from "./export-entries.ts"
+export * from "./types.ts"

package/src/domain/vault-catalog/types.ts

@@ -0,0 +1,114 @@
+import type { NoteFrontmatter, NoteLimits, ParsedNote } from "#src/domain/note"
+import type { Failed, Succeeded } from "#src/shared"
+
+export type VaultEntryKind = "note" | "folder" | "index" | "template" | "dashboard" | "temporary" | "other"
+
+export interface VaultFileStat {
+  size: number
+  mtimeMs: number
+  ctimeMs: number
+  device: number
+  inode: number
+}
+
+export interface VaultCatalogEntry {
+  path: string
+  kind: VaultEntryKind
+  archived: boolean
+  stat: VaultFileStat
+}
+
+export interface VaultCatalogFailure extends Failed {
+  path: string
+  scope: "file" | "directory" | "entry"
+  reason:
+    | "invalid-path"
+    | "outside-vault"
+    | "not-found"
+    | "not-directory"
+    | "not-file"
+    | "unreadable"
+    | "not-writable"
+    | "cycle"
+    | "excluded"
+    | "changed"
+    | "io-error"
+}
+
+export interface VaultAlias {
+  path: string
+  target: string
+}
+
+export interface VaultEnumeration {
+  entries: VaultCatalogEntry[]
+  observedPaths: string[]
+  completeDirectories: string[]
+  failures: VaultCatalogFailure[]
+  aliases: VaultAlias[]
+}
+
+export type VaultEnumerationResult = Succeeded<VaultEnumeration> | VaultCatalogFailure
+
+export interface AnalyzeVaultNoteRequest {
+  statement: string
+  text: string
+  archived: boolean
+  limits: NoteLimits
+}
+
+export interface VaultNoteProblems {
+  frontmatterProblems: string[]
+  nameProblems: string[]
+  bodyProblems: string[]
+}
+
+export interface ParsedVaultNote extends VaultNoteProblems {
+  status: "parsed"
+  parsed: ParsedNote
+  frontmatter: NoteFrontmatter | null
+  searchable: boolean
+  needsFixing: boolean
+}
+
+export interface UnclosedVaultNote extends VaultNoteProblems {
+  status: "unclosed"
+  searchable: false
+  needsFixing: true
+}
+
+export type VaultNoteAnalysis = ParsedVaultNote | UnclosedVaultNote
+
+export interface VaultFileRequest {
+  path: string
+}
+
+export interface InspectedVaultFile {
+  path: string
+  canonicalPath: string
+  text: string
+  rawHash: string
+  stat: VaultFileStat
+  archived: boolean
+  analysis: VaultNoteAnalysis
+}
+
+export type VaultInspectionResult = Succeeded<InspectedVaultFile> | VaultCatalogFailure
+
+export interface VaultExportFile {
+  path: string
+  bytes: Uint8Array
+  rawHash: string
+  stat: VaultFileStat
+}
+
+export interface VaultExportEntry {
+  path: string
+  bytes: Uint8Array
+}
+
+export interface VaultExportFailure extends Failed {
+  failures: VaultCatalogFailure[]
+}
+
+export type VaultExportResult = Succeeded<VaultExportFile[]> | VaultExportFailure

package/src/domain/vault-diagnosis/diagnose.ts

@@ -0,0 +1,79 @@
+import { catalogFolder } from "#src/domain/search-catalog"
+import { isRootArchive, type VaultCatalogEntry } from "#src/domain/vault-catalog"
+import type {
+  CrowdedFolder,
+  DuplicateNoteId,
+  InvalidVaultNote,
+  VaultDiagnosis,
+  VaultDiagnosisRequest,
+} from "./types.ts"
+
+export function diagnoseVault(request: VaultDiagnosisRequest): VaultDiagnosis {
+  return {
+    invalid: invalidNotes(request),
+    blank: request.inspected
+      .filter((file) => file.analysis.status === "unclosed")
+      .map((file) => file.path)
+      .sort(compareText),
+    duplicateIds: duplicateIds(request),
+    temporaries: request.entries
+      .filter((entry) => entry.kind === "temporary")
+      .map((entry) => entry.path)
+      .sort(compareText),
+    crowdedFolders: crowdedFolders(request),
+  }
+}
+
+function invalidNotes(request: VaultDiagnosisRequest): InvalidVaultNote[] {
+  const invalid: InvalidVaultNote[] = []
+  for (const file of request.inspected) {
+    const { analysis } = file
+    if (analysis.status === "parsed" && analysis.needsFixing) {
+      invalid.push({
+        path: file.path,
+        problems: [...analysis.frontmatterProblems, ...analysis.nameProblems, ...analysis.bodyProblems],
+      })
+    }
+  }
+  return invalid.sort((left, right) => compareText(left.path, right.path))
+}
+
+function duplicateIds(request: VaultDiagnosisRequest): DuplicateNoteId[] {
+  const groups = new Map<string, string[]>()
+  for (const file of request.inspected) {
+    const { analysis } = file
+    if (analysis.status !== "parsed" || !analysis.frontmatter) continue
+    const group = groups.get(analysis.frontmatter.id)
+    if (group) group.push(file.path)
+    else groups.set(analysis.frontmatter.id, [file.path])
+  }
+  return [...groups]
+    .filter(([, paths]) => paths.length > 1)
+    .map(([id, paths]) => ({ id, paths: paths.sort(compareText) }))
+    .sort((left, right) => compareText(left.id, right.id))
+}
+
+function crowdedFolders(request: VaultDiagnosisRequest): CrowdedFolder[] {
+  const counts = new Map<string, number>()
+  for (const entry of request.entries) {
+    if (!isLiveNote(entry)) continue
+    const folder = catalogFolder(entry.path)
+    const count = counts.get(folder)
+    if (count) counts.set(folder, count + 1)
+    else counts.set(folder, 1)
+  }
+  return [...counts]
+    .filter(([, count]) => count > request.limits.maxNotesPerFolder)
+    .map(([folder, count]) => ({ folder, count }))
+    .sort((left, right) => compareText(left.folder, right.folder))
+}
+
+function isLiveNote(entry: VaultCatalogEntry): boolean {
+  return entry.kind === "note" && !entry.archived && !isRootArchive(entry.path)
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1
+  if (left > right) return 1
+  return 0
+}

package/src/domain/vault-diagnosis/index.ts

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

package/src/domain/vault-diagnosis/types.ts

@@ -0,0 +1,31 @@
+import type { MemoryConfig } from "#src/domain/config"
+import type { InspectedVaultFile, VaultCatalogEntry } from "#src/domain/vault-catalog"
+
+export interface VaultDiagnosisRequest {
+  entries: readonly VaultCatalogEntry[]
+  inspected: readonly InspectedVaultFile[]
+  limits: MemoryConfig["limits"]
+}
+
+export interface InvalidVaultNote {
+  path: string
+  problems: string[]
+}
+
+export interface DuplicateNoteId {
+  id: string
+  paths: string[]
+}
+
+export interface CrowdedFolder {
+  folder: string
+  count: number
+}
+
+export interface VaultDiagnosis {
+  invalid: InvalidVaultNote[]
+  blank: string[]
+  duplicateIds: DuplicateNoteId[]
+  temporaries: string[]
+  crowdedFolders: CrowdedFolder[]
+}

package/src/domain/vault-path/constants.ts

@@ -0,0 +1,13 @@
+export const FOLDER_INDEX_NAME = "index"
+
+export const ARCHIVE_FOLDER = "archive"
+
+export const TEMPLATES_FOLDER = "_templates"
+
+export const RESERVED_ROOT_FOLDERS = [ARCHIVE_FOLDER, TEMPLATES_FOLDER]
+
+export const VAULT_PATH_SEPARATOR = "/"
+
+export const DRIVE_LETTER = /^[A-Za-z]:/
+
+export const HIDDEN_NAME_PREFIX = "."

package/src/domain/vault-path/index.ts

@@ -0,0 +1,2 @@
+export * from "./constants.ts"
+export * from "./vault-path.ts"

package/src/domain/vault-path/vault-path.ts

@@ -0,0 +1,65 @@
+import { checkEdges, checkFileSystemName, checkLinkCharacters, RELATIVE_NAMES } from "#src/domain/names"
+import { DRIVE_LETTER, HIDDEN_NAME_PREFIX, RESERVED_ROOT_FOLDERS, VAULT_PATH_SEPARATOR } from "./constants.ts"
+
+export function joinVaultPath(...parts: string[]): string {
+  return parts.filter((part) => part.length > 0).join(VAULT_PATH_SEPARATOR)
+}
+
+export function ancestorFolders(folder: string): string[] {
+  const parts = folder.split(VAULT_PATH_SEPARATOR).filter((part) => part.length > 0)
+  const nested = parts.map((_part, depth) => parts.slice(0, parts.length - depth).join(VAULT_PATH_SEPARATOR))
+
+  return [...nested, ""]
+}
+
+export function checkVaultPath(folder: string): string[] {
+  if (folder.includes("\\")) {
+    return ['folder: use "/" between folders']
+  }
+
+  if (folder.startsWith(VAULT_PATH_SEPARATOR) || DRIVE_LETTER.test(folder)) {
+    return ["folder: must be relative to the vault"]
+  }
+
+  if (folder.length === 0) {
+    return []
+  }
+
+  const problems = folder.split(VAULT_PATH_SEPARATOR).flatMap(checkFolderPart)
+  return [...new Set(problems)]
+}
+
+export function checkMemoryFolder(folder: string): string[] {
+  const problems = checkVaultPath(folder)
+  if (problems.length > 0 || folder.length === 0) {
+    return problems
+  }
+
+  return folder.split(VAULT_PATH_SEPARATOR).flatMap(checkMemoryFolderPart)
+}
+
+function checkFolderPart(part: string): string[] {
+  if (part.length === 0) {
+    return ["folder: has an empty part"]
+  }
+
+  if (RELATIVE_NAMES.includes(part)) {
+    return [`folder: "${part}" is not allowed`]
+  }
+
+  const label = `folder "${part}"`
+  return [...checkFileSystemName(label, part), ...checkLinkCharacters(label, part), ...checkEdges(label, part)]
+}
+
+function checkMemoryFolderPart(part: string, depth: number): string[] {
+  const isReservedRoot = depth === 0 && RESERVED_ROOT_FOLDERS.includes(part.toLowerCase())
+  if (isReservedRoot) {
+    return [`folder "${part}": is reserved for the vault`]
+  }
+
+  if (part.startsWith(HIDDEN_NAME_PREFIX)) {
+    return [`folder "${part}": is hidden (starts with ".")`]
+  }
+
+  return []
+}