pi-obsidian-memory 0.0.1 → 0.1.1

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

@@ -0,0 +1,8 @@
+import type { MemoryScope } from "#src/services"
+
+export type { FolderRead, ListMemoryResult } from "#src/usecases/list-memory/leased"
+
+export interface ListMemoryRequest {
+  vault: MemoryScope
+  folder: string
+}

package/src/usecases/load-dont-forget/index.ts

@@ -0,0 +1,2 @@
+export * from "./load-dont-forget.ts"
+export * from "./types.ts"

package/src/usecases/load-dont-forget/load-dont-forget.ts

@@ -0,0 +1,111 @@
+import {
+  closeIndex,
+  dontForgetCandidates,
+  inspectVaultFile,
+  isLoadedDontForget,
+  type OpenedIndex,
+  readIndexInventory,
+  type VaultNoteAnalysis,
+} from "#src/services"
+import {
+  type MemoryOperationContext,
+  memoryAdmissionRefusal,
+  memoryOperationInterruption,
+} from "#src/usecases/operation-context"
+import { type ResolvedMemory, type ResolvedVault, resolveLeasedMemory } from "#src/usecases/resolve-memory/leased"
+import { openVaultIndex, synchronizeOpenedMemory } from "#src/usecases/synchronize-memory/leased"
+import type { DontForgetVault, LoadDontForgetResult, LoadedDontForgetNote } from "./types.ts"
+
+export async function loadDontForget(context: MemoryOperationContext): Promise<LoadDontForgetResult> {
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) return memoryAdmissionRefusal(context)
+  try {
+    const memory = await resolveLeasedMemory(context)
+    if (!memory.succeeded) return memory
+    return await loadResolvedVaults(memory.output, context)
+  } finally {
+    lease.release()
+  }
+}
+
+async function loadResolvedVaults(
+  memory: ResolvedMemory,
+  context: MemoryOperationContext,
+): Promise<LoadDontForgetResult> {
+  const targets = [memory.global]
+  if (memory.project) targets.push(memory.project)
+  const vaults: DontForgetVault[] = []
+  for (const target of targets) {
+    const interrupted = memoryOperationInterruption(context)
+    if (interrupted) return interrupted
+    vaults.push(await loadLeasedVault(memory, target, context))
+  }
+  const stale = memoryOperationInterruption(context)
+  if (stale) return stale
+  return { succeeded: true, output: { vaults } }
+}
+
+async function loadLeasedVault(
+  memory: ResolvedMemory,
+  target: ResolvedVault,
+  context: MemoryOperationContext,
+): Promise<DontForgetVault> {
+  const opened = openVaultIndex(memory, target)
+  if (!opened.succeeded) return { vault: target.scope, notes: [], problems: opened.problems }
+  const result: DontForgetVault = { vault: target.scope, notes: [], problems: [] }
+  try {
+    await loadSynchronizedVault(result, opened, memory, target, context)
+  } finally {
+    const closed = closeIndex(opened.output)
+    if (!closed.succeeded) result.problems.push(...closed.problems)
+  }
+  return result
+}
+
+async function loadSynchronizedVault(
+  result: DontForgetVault,
+  opened: OpenedIndex,
+  memory: ResolvedMemory,
+  target: ResolvedVault,
+  context: MemoryOperationContext,
+): Promise<void> {
+  const synchronized = await synchronizeOpenedMemory(opened, memory, target, context, null)
+  if (!synchronized.succeeded) {
+    result.problems.push(...synchronized.problems)
+    return
+  }
+  const inventory = readIndexInventory(opened.output)
+  if (!inventory.succeeded) {
+    result.problems.push(...inventory.problems)
+    return
+  }
+  for (const path of dontForgetCandidates(inventory.output).sort()) {
+    if (memoryOperationInterruption(context)) return
+    const inspected = await inspectVaultFile(target.vault, { path })
+    if (!inspected.succeeded) {
+      result.problems.push(...inspected.problems)
+      continue
+    }
+    const note = loadedNote(target, path, inspected.output.analysis, inspected.output.rawHash)
+    if (note) result.notes.push(note)
+  }
+}
+
+function loadedNote(
+  target: ResolvedVault,
+  path: string,
+  analysis: VaultNoteAnalysis,
+  hash: string,
+): LoadedDontForgetNote | null {
+  if (!isLoadedDontForget(analysis) || analysis.status !== "parsed" || !analysis.frontmatter) return null
+  return {
+    vault: target.scope,
+    path,
+    type: analysis.frontmatter.type,
+    id: analysis.frontmatter.id,
+    hash,
+    statement: analysis.parsed.statement,
+    body: analysis.parsed.body,
+    problems: [...analysis.frontmatterProblems, ...analysis.nameProblems, ...analysis.bodyProblems],
+  }
+}

package/src/usecases/load-dont-forget/types.ts

@@ -0,0 +1,26 @@
+import type { CatalogHit, MemoryScope } from "#src/services"
+import type { Succeeded } from "#src/shared"
+import type { MemoryResolutionRefusal } from "#src/usecases/resolve-memory"
+
+export interface LoadedDontForgetNote {
+  vault: MemoryScope
+  path: string
+  type: CatalogHit["type"]
+  id: string
+  hash: string
+  statement: string
+  body: string
+  problems: string[]
+}
+
+export interface DontForgetVault {
+  vault: MemoryScope
+  notes: LoadedDontForgetNote[]
+  problems: string[]
+}
+
+export interface LoadedDontForget {
+  vaults: DontForgetVault[]
+}
+
+export type LoadDontForgetResult = Succeeded<LoadedDontForget> | MemoryResolutionRefusal

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

@@ -0,0 +1,42 @@
+import {
+  captureMemoryOperationContext,
+  type MemoryOperationContext,
+  memoryAdmissionRefusal,
+  memoryOperationInterruption,
+} from "#src/usecases/operation-context"
+import { resolveLeasedMemory, selectMemoryVault } from "#src/usecases/resolve-memory/leased"
+import type { MemoryAddress } from "#src/usecases/session"
+import { receiptedNote } from "./receipt.ts"
+import type { ApplyChange, ChangeOutcome, ChangeRefusal } from "./types.ts"
+
+export async function changeLeasedMemory<Result extends ChangeOutcome>(
+  address: MemoryAddress,
+  callerContext: MemoryOperationContext,
+  apply: ApplyChange<Result>,
+): Promise<Result | ChangeRefusal> {
+  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
+    const memory = await resolveLeasedMemory(context)
+    if (!memory.succeeded) return memory
+    const stale = memoryOperationInterruption(context)
+    if (stale) return stale
+    const target = selectMemoryVault(memory.output, address.vault)
+    if (!target.succeeded) return target
+    const receipted = receiptedNote(context, address, target.output.vault.path)
+    if (!receipted.succeeded) return receipted
+    const result = await apply({ target: target.output, context, receipted: receipted.output })
+    if (consumesReceipt(result)) context.session.consumeReceipt(context.stamp, address)
+    return result
+  } finally {
+    lease.release()
+  }
+}
+
+function consumesReceipt(result: ChangeOutcome): boolean {
+  if (result.succeeded) return true
+  return result.reason === "conflict" || result.reason === "partial"
+}

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

@@ -0,0 +1,5 @@
+export * from "./change.ts"
+export * from "./maintenance.ts"
+export * from "./partial.ts"
+export * from "./receipt.ts"
+export * from "./types.ts"

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

@@ -0,0 +1,11 @@
+import type { MaintenanceWarnings, RefreshResult } from "#src/services"
+
+export function refreshWarnings(refreshed: RefreshResult): string[] {
+  if (!refreshed.succeeded) return refreshed.problems.map((problem) => `${refreshed.reason}: ${problem}`)
+  return warningsOf(refreshed)
+}
+
+export function warningsOf(result: MaintenanceWarnings): string[] {
+  if (result.maintenanceProblems) return [...result.maintenanceProblems]
+  return []
+}

package/src/usecases/memory-change/partial.ts

@@ -0,0 +1,18 @@
+import { displayNotePath, type PartialRelocation } from "#src/services"
+import type { Failed } from "#src/shared"
+import type { PartialMemoryChange } from "./types.ts"
+
+export function reportPartial<Other extends Failed>(result: Other | PartialRelocation): Other | PartialMemoryChange {
+  if (!("written" in result)) return result
+  return describePartial(result)
+}
+
+function describePartial(partial: PartialRelocation): PartialMemoryChange {
+  return {
+    succeeded: false,
+    reason: "partial",
+    problems: partial.problems,
+    published: partial.written.map((placed) => displayNotePath(placed.folder, placed.note.statement)),
+    originalState: partial.originalState,
+  }
+}

package/src/usecases/memory-change/receipt.ts

@@ -0,0 +1,40 @@
+import type { Note } from "#src/services"
+import type { MemoryOperationContext } from "#src/usecases/operation-context"
+import type { DeliveredRead, MemoryAddress } from "#src/usecases/session"
+import type { ReceiptRefusal, ReceiptResult } from "./types.ts"
+
+export function receiptedNote(
+  context: MemoryOperationContext,
+  address: MemoryAddress,
+  canonicalVault: string,
+): ReceiptResult {
+  const read = context.session.getReceipt(context.stamp, address)
+  if (!read) {
+    return refuse("not-read", `${address.path} was not read with memory_get in this session`)
+  }
+  if (read.canonicalVault !== canonicalVault) {
+    return refuse("stale-vault", `the vault registered for ${address.vault} changed since ${address.path} was read`)
+  }
+  if (read.archived) {
+    return refuse("archived", `${address.path} is archived and archived notes are not changed`)
+  }
+  const note = noteOf(read)
+  if (!note) {
+    return refuse("needs-fixing", `${address.path} has no valid frontmatter`)
+  }
+  return { succeeded: true, output: { read, note, folder: folderOf(read.path) } }
+}
+
+function noteOf(read: DeliveredRead): Note | null {
+  const { analysis } = read
+  if (!analysis.frontmatter) return null
+  return { statement: analysis.parsed.statement, frontmatter: analysis.frontmatter, body: analysis.parsed.body }
+}
+
+function folderOf(path: string): string {
+  return path.slice(0, Math.max(0, path.lastIndexOf("/")))
+}
+
+function refuse(reason: ReceiptRefusal["reason"], problem: string): ReceiptRefusal {
+  return { succeeded: false, reason, problems: [problem] }
+}

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

@@ -0,0 +1,44 @@
+import type { NoProjectRefusal, Note, PartialRelocation } from "#src/services"
+import type { Failed, Succeeded } from "#src/shared"
+import type { MemoryOperationContext } from "#src/usecases/operation-context"
+import type { MemoryResolutionRefusal, ResolvedVault } from "#src/usecases/resolve-memory"
+import type { DeliveredRead } from "#src/usecases/session"
+
+export interface ReceiptedNote {
+  read: DeliveredRead
+  note: Note
+  folder: string
+}
+
+export interface ReceiptRefusal extends Failed {
+  reason: "not-read" | "stale-vault" | "needs-fixing" | "archived"
+}
+
+export type ReceiptResult = Succeeded<ReceiptedNote> | ReceiptRefusal
+
+export interface PartialMemoryChange extends Failed {
+  reason: "partial"
+  published: string[]
+  originalState: PartialRelocation["originalState"]
+}
+
+export interface LeasedChange {
+  target: ResolvedVault
+  context: MemoryOperationContext
+  receipted: ReceiptedNote
+}
+
+export interface ChangeOutcomeFailure {
+  succeeded: false
+  reason: string
+}
+
+export interface ChangeOutcomeSuccess {
+  succeeded: true
+}
+
+export type ChangeOutcome = ChangeOutcomeSuccess | ChangeOutcomeFailure
+
+export type ApplyChange<Result extends ChangeOutcome> = (change: LeasedChange) => Promise<Result>
+
+export type ChangeRefusal = MemoryResolutionRefusal | NoProjectRefusal | ReceiptRefusal

package/src/usecases/operation-context/context.ts

@@ -0,0 +1,37 @@
+import type { MemoryOperationContext, MemoryOperationRefusal } from "./types.ts"
+
+export function captureMemoryOperationContext(context: MemoryOperationContext): MemoryOperationContext {
+  const captured: MemoryOperationContext = {
+    configPath: context.configPath,
+    workingFolder: context.workingFolder,
+    indexPath: context.indexPath,
+    platform: context.platform,
+    session: context.session,
+    stamp: context.stamp,
+    signal: context.signal,
+  }
+  if (context.semantic) captured.semantic = context.semantic
+  return captured
+}
+
+export function memoryOperationInterruption(context: MemoryOperationContext): MemoryOperationRefusal | null {
+  if (!context.session.isCurrent(context.stamp)) return staleMemorySession()
+  if (context.signal.aborted) {
+    return { succeeded: false, reason: "cancelled", problems: ["Memory read cancelled; retry with a live signal"] }
+  }
+  return null
+}
+
+export function staleMemorySession(): MemoryOperationRefusal {
+  return {
+    succeeded: false,
+    reason: "stale-session",
+    problems: ["Memory session or configuration changed; retry with a fresh session stamp"],
+  }
+}
+
+export function memoryAdmissionRefusal(context: MemoryOperationContext): MemoryOperationRefusal {
+  const interrupted = memoryOperationInterruption(context)
+  if (interrupted) return interrupted
+  return { succeeded: false, reason: "admission-refused", problems: ["Memory session is not accepting operations"] }
+}

package/src/usecases/operation-context/index.ts

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

package/src/usecases/operation-context/types.ts

@@ -0,0 +1,19 @@
+import type { PathPlatform } from "#src/services"
+import type { Failed } from "#src/shared"
+import type { SemanticSource } from "#src/usecases/semantic-port"
+import type { MemorySession, OperationStamp } from "#src/usecases/session"
+
+export interface MemoryOperationContext {
+  configPath: string
+  workingFolder: string
+  indexPath: string
+  platform: PathPlatform
+  session: MemorySession
+  stamp: OperationStamp
+  signal: AbortSignal
+  semantic?: SemanticSource
+}
+
+export interface MemoryOperationRefusal extends Failed {
+  reason: "cancelled" | "stale-session" | "admission-refused"
+}

package/src/usecases/registration/check.ts

@@ -0,0 +1,6 @@
+import { type ReadConfigResult, readConfig } from "#src/services"
+import type { MemoryContext } from "#src/usecases/add-memory"
+
+export function checkMemoryConfig(context: MemoryContext): Promise<ReadConfigResult> {
+  return readConfig(context.configPath, context.platform)
+}

package/src/usecases/registration/entry.ts

@@ -0,0 +1,33 @@
+import type { ChatModelReference, RegistrationContext, SetupCommitCaptureResult, SetupCommitRequest } from "./types.ts"
+
+export function captureRegistrationContext(context: RegistrationContext): RegistrationContext {
+  return {
+    configPath: context.configPath,
+    workingFolder: context.workingFolder,
+    indexPath: context.indexPath,
+    platform: context.platform,
+    session: context.session,
+    stamp: context.stamp,
+    signal: context.signal,
+  }
+}
+
+export function captureSelectedModel(model: ChatModelReference | null): ChatModelReference | null {
+  if (!model) return null
+  return { ...model }
+}
+
+export function captureSetupCommit(request: SetupCommitRequest): SetupCommitCaptureResult {
+  try {
+    return {
+      succeeded: true,
+      output: {
+        config: structuredClone(request.config),
+        expectedHash: request.expectedHash,
+        replacementConfirmed: request.replacementConfirmed,
+      },
+    }
+  } catch (error) {
+    return { succeeded: false, problems: [`setup config could not be captured: ${String(error)}`] }
+  }
+}

package/src/usecases/registration/index.ts

@@ -0,0 +1,8 @@
+export * from "./check.ts"
+export * from "./entry.ts"
+export * from "./init.ts"
+export * from "./prepare.ts"
+export * from "./prepare-init.ts"
+export * from "./propose.ts"
+export * from "./setup.ts"
+export * from "./types.ts"

package/src/usecases/registration/init.ts

@@ -0,0 +1,94 @@
+import {
+  canonicalizeRegistration,
+  type MemoryConfig,
+  proposeInit,
+  readConfigSnapshot,
+  resolveRegistrationVault,
+} from "#src/services"
+import { captureRegistrationContext } from "./entry.ts"
+import { publishRegistration, registrationInterruption, registrationValidationFailure } from "./publication.ts"
+import type { InitCommitRequest, RegistrationContext, RegistrationResult } from "./types.ts"
+
+export async function initProjectMemory(
+  input: InitCommitRequest,
+  callerContext: RegistrationContext,
+): Promise<RegistrationResult> {
+  const context = captureRegistrationContext(callerContext)
+  const request = { name: input.name, vault: input.vault, expectedHash: input.expectedHash }
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) {
+    return registrationValidationFailure({ succeeded: false, problems: ["registration session admission refused"] })
+  }
+  try {
+    const interrupted = registrationInterruption(context)
+    if (interrupted) return registrationValidationFailure(interrupted)
+    return await prepareProjectRegistration(request, context)
+  } finally {
+    lease.release()
+  }
+}
+
+async function prepareProjectRegistration(
+  request: InitCommitRequest,
+  context: RegistrationContext,
+): Promise<RegistrationResult> {
+  const snapshot = await readConfigSnapshot({ path: context.configPath, platform: context.platform })
+  const interrupted = registrationInterruption(context)
+  if (interrupted) return registrationValidationFailure(interrupted)
+  if (!snapshot.succeeded) return registrationValidationFailure(snapshot)
+  if (snapshot.output.state === "missing") {
+    return registrationValidationFailure({
+      succeeded: false,
+      reason: "not-configured",
+      configPath: context.configPath,
+      problems: ["project registration requires a configured global vault"],
+    })
+  }
+  if (snapshot.output.hash !== request.expectedHash) {
+    return registrationValidationFailure({
+      succeeded: false,
+      reason: "conflict",
+      problems: ["config changed since it was read"],
+      warnings: [],
+    })
+  }
+  const parsed = snapshot.output.lexicalParse
+  if (!parsed.succeeded) return registrationValidationFailure(parsed)
+  return proposeProjectRegistration(request, context, parsed.output)
+}
+
+async function proposeProjectRegistration(
+  request: InitCommitRequest,
+  context: RegistrationContext,
+  config: MemoryConfig,
+): Promise<RegistrationResult> {
+  const valid = await canonicalizeRegistration({
+    config,
+    configPath: context.configPath,
+    indexPath: context.indexPath,
+    platform: context.platform,
+  })
+  const stale = registrationInterruption(context)
+  if (stale) return registrationValidationFailure(stale)
+  if (!valid.succeeded) return registrationValidationFailure(valid)
+  const vault = resolveRegistrationVault({ vault: request.vault, workingFolder: context.workingFolder })
+  if (!vault.succeeded) return registrationValidationFailure(vault)
+  const proposal = proposeInit(
+    { config, folder: context.workingFolder, name: request.name, vault: vault.output },
+    context.platform,
+  )
+  if (!proposal.succeeded) return registrationValidationFailure(proposal)
+  return publishRegistration(
+    {
+      scope: "project",
+      write: {
+        path: context.configPath,
+        platform: context.platform,
+        indexPath: context.indexPath,
+        config: proposal.output,
+        expectedHash: request.expectedHash,
+      },
+    },
+    context,
+  )
+}

package/src/usecases/registration/prepare-init.ts

@@ -0,0 +1,43 @@
+import { basename } from "node:path"
+
+import { type ProjectEntry, readConfigSnapshot, resolveProject } from "#src/services"
+import type { MemoryContext } from "#src/usecases/add-memory"
+import type { InitPreparation, InitPreparationResult, ProjectNameResult } from "./types.ts"
+
+export async function prepareProjectInit(context: MemoryContext): Promise<InitPreparationResult> {
+  const snapshot = await readConfigSnapshot({ path: context.configPath, platform: context.platform })
+  if (!snapshot.succeeded) {
+    return { succeeded: false, reason: "unreadable", configPath: context.configPath, problems: snapshot.problems }
+  }
+  if (snapshot.output.state === "missing") {
+    return {
+      succeeded: false,
+      reason: "not-configured",
+      configPath: context.configPath,
+      problems: ["memory is not configured"],
+    }
+  }
+  const parsed = snapshot.output.lexicalParse
+  if (!parsed.succeeded) {
+    return { succeeded: false, reason: "invalid-config", configPath: context.configPath, problems: parsed.problems }
+  }
+  const registered = resolveProject(parsed.output, context.workingFolder, context.platform)
+  let existing: ProjectEntry | null = null
+  let defaultName = basename(context.workingFolder)
+  if (registered.succeeded) {
+    existing = registered.output
+    defaultName = registered.output.name
+  }
+  const takenNames = parsed.output.projects.filter((project) => project !== existing).map((project) => project.name)
+  return { succeeded: true, output: { expectedHash: snapshot.output.hash, existing, defaultName, takenNames } }
+}
+
+export function checkProjectName(preparation: InitPreparation, answer: string): ProjectNameResult {
+  let name = answer.trim()
+  if (name === "") name = preparation.defaultName
+  const lowered = name.toLowerCase()
+  if (preparation.takenNames.some((taken) => taken.toLowerCase() === lowered)) {
+    return { succeeded: false, problems: [`a project named "${name}" is already registered`] }
+  }
+  return { succeeded: true, output: name }
+}

package/src/usecases/registration/prepare.ts

@@ -0,0 +1,35 @@
+import { prepareSetupDefaults, readConfigSnapshot } from "#src/services"
+import { captureRegistrationContext, captureSelectedModel } from "./entry.ts"
+import { registrationInterruption } from "./publication.ts"
+import type { RegistrationContext, SetupPreparationRequest, SetupPreparationResult } from "./types.ts"
+
+export async function prepareMemorySetup(
+  input: SetupPreparationRequest,
+  callerContext: RegistrationContext,
+): Promise<SetupPreparationResult> {
+  const context = captureRegistrationContext(callerContext)
+  const selectedModel = captureSelectedModel(input.selectedModel)
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) return { succeeded: false, problems: ["registration session admission refused"] }
+  try {
+    const interrupted = registrationInterruption(context)
+    if (interrupted) return interrupted
+    const snapshot = await readConfigSnapshot({ path: context.configPath, platform: context.platform })
+    const stale = registrationInterruption(context)
+    if (stale) return stale
+    if (!snapshot.succeeded) return snapshot
+    const defaults = prepareSetupDefaults(selectedModel)
+    let draft = defaults
+    if (snapshot.output.state === "present") {
+      const repair = snapshot.output.repair
+      draft = {
+        ...repair,
+        capture: { ...repair.capture, model: { ...defaults.capture.model, ...repair.capture.model } },
+        memoryAgent: { model: { ...defaults.memoryAgent.model, ...repair.memoryAgent.model } },
+      }
+    }
+    return { succeeded: true, output: { snapshot: snapshot.output, draft, selectedModel } }
+  } finally {
+    lease.release()
+  }
+}

package/src/usecases/registration/propose.ts

@@ -0,0 +1,34 @@
+import { inspectVaultFolder, proposeSetup, resolveRegistrationVault, setupDisclosures } from "#src/services"
+import type { Failed } from "#src/shared"
+import type { MemoryContext } from "#src/usecases/add-memory"
+import type { SetupProposalRequest, SetupProposalResult, SetupVaultMode } from "./types.ts"
+
+export async function proposeMemorySetup(
+  request: SetupProposalRequest,
+  context: MemoryContext,
+): Promise<SetupProposalResult> {
+  let requested = request.vault.trim()
+  if (requested === "" && request.draft.global.vault) requested = request.draft.global.vault
+  const vault = resolveRegistrationVault({ vault: requested, workingFolder: context.workingFolder })
+  if (!vault.succeeded) return vault
+  const refusal = await vaultFolderRefusal(vault.output, request.mode)
+  if (refusal) return refusal
+  const proposal = proposeSetup({ config: request.draft, vault: vault.output }, context.platform)
+  if (!proposal.succeeded) return proposal
+  return { succeeded: true, output: { config: proposal.output, disclosures: setupDisclosures(proposal.output) } }
+}
+
+async function vaultFolderRefusal(vault: string, mode: SetupVaultMode): Promise<Failed | null> {
+  const folder = await inspectVaultFolder(vault)
+  if (!folder.succeeded) return folder
+  if (folder.output === "not-directory") {
+    return { succeeded: false, problems: [`${vault} is not a folder`] }
+  }
+  if (mode === "create" && folder.output === "populated") {
+    return { succeeded: false, problems: [`${vault} already has files; attach it instead of creating a new vault`] }
+  }
+  if (mode === "attach" && folder.output === "missing") {
+    return { succeeded: false, problems: [`${vault} does not exist; create it instead of attaching`] }
+  }
+  return null
+}