pi-obsidian-memory 0.0.0 → 0.1.0

package/src/services/search-index/vector-storage.ts

@@ -0,0 +1,169 @@
+import { Value } from "typebox/value"
+
+import { type VectorChunk, type VectorGeneration, VectorGenerationSchema, type VectorReplacement } from "#src/domain"
+import type { Succeeded } from "#src/shared"
+import type { prepareCatalogStatements } from "./catalog-statements.ts"
+import { corruptCatalog } from "./inventory.ts"
+import { invalidCatalog, staleCatalog } from "./reconcile.ts"
+import {
+  CatalogStateSchema,
+  VectorChunkSchema,
+  VectorReplacementSchema,
+  VectorRowSchema,
+  VectorUpdateSchema,
+  VectorValuesSchema,
+} from "./schemas.ts"
+import type {
+  IndexWriteResult,
+  SearchIndexRefusal,
+  VectorCacheResult,
+  VectorCoverageResult,
+  VectorUpdate,
+} from "./types.ts"
+import type { prepareVectorStatements } from "./vector-statements.ts"
+
+export function readVectors(statements: ReturnType<typeof prepareVectorStatements>): VectorCacheResult {
+  const generation = statements.generation.get()
+  const rows = statements.chunks.all()
+  if (!generation) {
+    if (rows.length > 0) return corruptCatalog()
+    return { succeeded: true, output: { generation: null, chunks: [] } }
+  }
+  if (!Value.Check(VectorGenerationSchema, generation)) return corruptCatalog()
+  const chunks: VectorChunk[] = []
+  for (const row of rows) {
+    if (!Value.Check(VectorRowSchema, row)) return corruptCatalog()
+    const vector = JSON.parse(row.vector)
+    if (!Value.Check(VectorValuesSchema, vector)) return corruptCatalog()
+    const chunk = { contentFingerprint: row.content_fingerprint, chunk: row.chunk, vector }
+    if (!Value.Check(VectorChunkSchema, chunk) || !validVector(chunk.vector, generation.dimensions)) {
+      return corruptCatalog()
+    }
+    chunks.push(chunk)
+  }
+  if (!contiguousChunks(chunks)) return corruptCatalog()
+  return { succeeded: true, output: { generation, chunks } }
+}
+
+export function writeVectors(
+  statements: ReturnType<typeof prepareVectorStatements>,
+  catalog: ReturnType<typeof prepareCatalogStatements>,
+  request: VectorReplacement,
+): IndexWriteResult {
+  if (!Value.Check(VectorReplacementSchema, request)) return invalidCatalog("invalid vector generation")
+  const current = readCurrentContent(statements, catalog, request.expectedRevision)
+  if (!current.succeeded) return current
+  if (!usableChunks(request.chunks, request.generation, current.output)) {
+    return invalidCatalog("vectors must belong to current content with finite nonzero vectors of one dimension")
+  }
+
+  statements.clearChunks.run()
+  statements.clearGeneration.run()
+  statements.putGeneration.run(request.generation.fingerprint, request.generation.dimensions)
+  for (const chunk of request.chunks) putChunk(statements, chunk)
+  return { succeeded: true }
+}
+
+export function updateVectors(
+  statements: ReturnType<typeof prepareVectorStatements>,
+  catalog: ReturnType<typeof prepareCatalogStatements>,
+  request: VectorUpdate,
+): IndexWriteResult {
+  if (!Value.Check(VectorUpdateSchema, request)) return invalidCatalog("invalid vector update")
+  const current = readCurrentContent(statements, catalog, request.expectedRevision)
+  if (!current.succeeded) return current
+  const added = new Set(request.add.map((chunk) => chunk.contentFingerprint))
+  if (
+    !usableChunks(request.add, request.generation, current.output) ||
+    request.remove.some((entry) => added.has(entry))
+  ) {
+    return invalidCatalog("added vectors must belong to current content, be finite, nonzero and not also removed")
+  }
+  const stored = readGeneration(statements)
+  if (!stored.succeeded) return stored
+  if (!sameGeneration(stored.output, request.generation)) {
+    statements.clearChunks.run()
+    statements.clearGeneration.run()
+    statements.putGeneration.run(request.generation.fingerprint, request.generation.dimensions)
+  }
+
+  for (const fingerprint of [...request.remove, ...added]) statements.removeChunks.run(fingerprint)
+  for (const chunk of request.add) putChunk(statements, chunk)
+  return { succeeded: true }
+}
+
+export function readVectorCoverage(statements: ReturnType<typeof prepareVectorStatements>): VectorCoverageResult {
+  const generation = readGeneration(statements)
+  if (!generation.succeeded) return generation
+  const embedded = statements.embeddedContent.get()
+  if (!embedded || typeof embedded.embedded !== "number") return corruptCatalog()
+  const current = readFingerprints(statements)
+  if (!current.succeeded) return current
+  return {
+    succeeded: true,
+    output: { generation: generation.output, embedded: embedded.embedded, current: current.output.size },
+  }
+}
+
+function readGeneration(
+  statements: ReturnType<typeof prepareVectorStatements>,
+): Succeeded<VectorGeneration | null> | SearchIndexRefusal {
+  const row = statements.generation.get()
+  if (!row) return { succeeded: true, output: null }
+  if (!Value.Check(VectorGenerationSchema, row)) return corruptCatalog()
+  return { succeeded: true, output: row }
+}
+
+function readCurrentContent(
+  statements: ReturnType<typeof prepareVectorStatements>,
+  catalog: ReturnType<typeof prepareCatalogStatements>,
+  expectedRevision: number,
+): Succeeded<Set<string>> | SearchIndexRefusal {
+  const state = catalog.state.get()
+  if (!Value.Check(CatalogStateSchema, state)) return corruptCatalog()
+  if (state.revision !== expectedRevision) return staleCatalog()
+  return readFingerprints(statements)
+}
+
+function readFingerprints(
+  statements: ReturnType<typeof prepareVectorStatements>,
+): Succeeded<Set<string>> | SearchIndexRefusal {
+  const fingerprints = new Set<string>()
+  for (const row of statements.currentContent.all()) {
+    if (typeof row.content_fingerprint !== "string") return corruptCatalog()
+    fingerprints.add(row.content_fingerprint)
+  }
+  return { succeeded: true, output: fingerprints }
+}
+
+function sameGeneration(stored: VectorGeneration | null, requested: VectorGeneration): boolean {
+  return stored?.fingerprint === requested.fingerprint && stored.dimensions === requested.dimensions
+}
+
+function putChunk(statements: ReturnType<typeof prepareVectorStatements>, chunk: VectorChunk): void {
+  statements.putChunk.run(chunk.contentFingerprint, chunk.chunk, JSON.stringify(chunk.vector))
+}
+
+function usableChunks(chunks: VectorChunk[], generation: VectorGeneration, current: Set<string>): boolean {
+  return (
+    chunks.every(
+      (chunk) => current.has(chunk.contentFingerprint) && validVector(chunk.vector, generation.dimensions),
+    ) && contiguousChunks(chunks)
+  )
+}
+
+function contiguousChunks(chunks: VectorChunk[]): boolean {
+  const groups = new Map<string, number[]>()
+  for (const chunk of chunks) {
+    const group = groups.get(chunk.contentFingerprint)
+    if (group) group.push(chunk.chunk)
+    else groups.set(chunk.contentFingerprint, [chunk.chunk])
+  }
+  return [...groups.values()].every((group) =>
+    group.sort((left, right) => left - right).every((chunk, index) => chunk === index),
+  )
+}
+
+function validVector(vector: number[], dimensions: number): boolean {
+  return vector.length === dimensions && vector.every(Number.isFinite) && vector.some((value) => value !== 0)
+}

package/src/services/search-index/vectors.ts

@@ -0,0 +1,18 @@
+import type { VectorReplacement } from "#src/domain"
+import type { IndexWriteResult, SearchIndex, VectorCacheResult, VectorCoverageResult, VectorUpdate } from "./types.ts"
+
+export function readVectorCache(index: SearchIndex): VectorCacheResult {
+  return index.vectors()
+}
+
+export function replaceVectorCache(index: SearchIndex, request: VectorReplacement): IndexWriteResult {
+  return index.replaceVectors(request)
+}
+
+export function updateVectorCache(index: SearchIndex, request: VectorUpdate): IndexWriteResult {
+  return index.updateVectors(request)
+}
+
+export function readVectorCoverage(index: SearchIndex): VectorCoverageResult {
+  return index.vectorCoverage()
+}

package/src/services/search-index/write.ts

@@ -0,0 +1,9 @@
+import type { IndexEntry, IndexWriteResult, SearchIndex } from "./types.ts"
+
+export function putNote(index: SearchIndex, entry: IndexEntry): IndexWriteResult {
+  return index.put(entry)
+}
+
+export function removeNote(index: SearchIndex, id: string): IndexWriteResult {
+  return index.remove(id)
+}

package/src/services/shell-edit/ask.ts

@@ -0,0 +1,53 @@
+import { Value } from "typebox/value"
+
+import { SHELL_EDIT_QUESTIONS } from "#src/domain"
+import { answeredByRequestedModel, defaultJevModel } from "#src/services/decision-model"
+import { JevOutcomeSchema, ShellEditAnswersSchema } from "./schemas.ts"
+import type { ShellEditAskCall, ShellEditAskResult, ShellEditClassifierResult } from "./types.ts"
+
+export async function askShellEdit(call: ShellEditAskCall): Promise<ShellEditAskResult> {
+  if (call.signal.aborted) return failed("cancelled")
+  const outcome = await classified(call)
+  if (typeof outcome === "string") return failed(outcome)
+  if (call.signal.aborted) return failed("cancelled")
+  if (!Value.Check(JevOutcomeSchema, outcome)) return failed("Jev returned an answer of another shape")
+  if (outcome.stopReason === "aborted") return failed("cancelled")
+  if (outcome.stopReason === "error") return failed(errorText(outcome.errorMessage))
+  if (!answeredByRequestedModel(defaultJevModel, outcome.model)) {
+    return failed(`answered by ${outcome.model}, not ${defaultJevModel}`)
+  }
+  if (!Value.Check(ShellEditAnswersSchema, outcome)) {
+    return failed("Jev did not answer every question with a yes/no probability")
+  }
+  const { answers } = outcome
+  const scores = {
+    redirection: answers.redirection.probability,
+    in_place: answers.in_place.probability,
+    inline_code: answers.inline_code.probability,
+    script_writes: answers.script_writes.probability,
+    copy_download: answers.copy_download.probability,
+    hardlink: answers.hardlink.probability,
+  }
+  return { succeeded: true, output: { scores, reportedModel: outcome.model } }
+}
+
+async function classified(call: ShellEditAskCall): Promise<ShellEditClassifierResult | string> {
+  try {
+    return await call.classifier.classify({
+      model: { provider: "typesafe", id: defaultJevModel },
+      context: { state: call.state, questions: SHELL_EDIT_QUESTIONS },
+      options: { signal: call.signal, maxRetries: 0 },
+    })
+  } catch (error) {
+    return `the call to Jev failed: ${String(error)}`
+  }
+}
+
+function errorText(message: string | undefined): string {
+  if (typeof message === "string") return `Jev reported an error: ${message}`
+  return "Jev reported an error"
+}
+
+function failed(cause: string): ShellEditAskResult {
+  return { succeeded: false, problems: [cause] }
+}

package/src/services/shell-edit/domain-rules.ts

@@ -0,0 +1,2 @@
+export type { ShellEditQuestion } from "#src/domain"
+export { executedFiles, firedQuestions, SHELL_EDIT_CUTOFFS, shellEditRefusal, shellEditUncheckable } from "#src/domain"

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

@@ -0,0 +1,4 @@
+export * from "./ask.ts"
+export * from "./domain-rules.ts"
+export * from "./schemas.ts"
+export * from "./types.ts"

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

@@ -0,0 +1,23 @@
+import Type from "typebox"
+
+const BoolAnswerSchema = Type.Object({
+  type: Type.Literal("bool"),
+  probability: Type.Number({ minimum: 0, maximum: 1 }),
+})
+
+export const JevOutcomeSchema = Type.Object({
+  stopReason: Type.Union([Type.Literal("stop"), Type.Literal("error"), Type.Literal("aborted")]),
+  model: Type.String(),
+  errorMessage: Type.Optional(Type.String()),
+})
+
+export const ShellEditAnswersSchema = Type.Object({
+  answers: Type.Object({
+    redirection: BoolAnswerSchema,
+    in_place: BoolAnswerSchema,
+    inline_code: BoolAnswerSchema,
+    script_writes: BoolAnswerSchema,
+    copy_download: BoolAnswerSchema,
+    hardlink: BoolAnswerSchema,
+  }),
+})

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

@@ -0,0 +1,61 @@
+import type { ShellEditQuestions, ShellEditScores, ShellEditState } from "#src/domain"
+import type { Failed, Succeeded } from "#src/shared"
+
+export interface ShellEditPrompt {
+  state: ShellEditState
+  questions: ShellEditQuestions
+}
+
+export interface ShellEditModelReference {
+  provider: "typesafe"
+  id: string
+}
+
+export interface ShellEditClassifyOptions {
+  signal: AbortSignal
+  maxRetries: 0
+}
+
+export interface ShellEditClassifyRequest {
+  model: ShellEditModelReference
+  context: ShellEditPrompt
+  options: ShellEditClassifyOptions
+}
+
+export interface ShellEditJevAnswer {
+  type: string
+  probability?: number
+}
+
+export interface ShellEditJevAnswers {
+  redirection?: ShellEditJevAnswer
+  in_place?: ShellEditJevAnswer
+  inline_code?: ShellEditJevAnswer
+  script_writes?: ShellEditJevAnswer
+  copy_download?: ShellEditJevAnswer
+  hardlink?: ShellEditJevAnswer
+}
+
+export interface ShellEditClassifierResult {
+  model: string
+  answers: ShellEditJevAnswers
+  stopReason: "stop" | "error" | "aborted"
+  errorMessage?: string
+}
+
+export interface ShellEditClassifierPort {
+  classify(request: ShellEditClassifyRequest): Promise<ShellEditClassifierResult>
+}
+
+export interface ShellEditAskCall {
+  classifier: ShellEditClassifierPort
+  state: ShellEditState
+  signal: AbortSignal
+}
+
+export interface ShellEditClassification {
+  scores: ShellEditScores
+  reportedModel: string
+}
+
+export type ShellEditAskResult = Succeeded<ShellEditClassification> | Failed

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

@@ -0,0 +1 @@
+export const PACKAGE_SCRIPT_PREFIX = "package.json#scripts."

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