@lef237/hagumi 0.0.0-stage → 0.1.0

package/src/tools/edit.ts

@@ -0,0 +1,32 @@
+import type { Tool } from "."
+import { apply, current } from "./change"
+
+export const edit: Tool = {
+  name: "edit",
+  kind: "act",
+  description:
+    "Replace one exact piece of text in a file inside the working directory. Read the file first. " +
+    "old_text must appear exactly once; include surrounding lines to make it unique. The user approves every change.",
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Relative to the working directory." },
+      old_text: { type: "string", description: "The exact text to replace, as it is in the file." },
+      new_text: { type: "string", description: "The text to put in its place." },
+    },
+    required: ["path", "old_text", "new_text"],
+    additionalProperties: false,
+  },
+  async plan(input, context) {
+    const path = String(input.path)
+    const oldText = String(input.old_text)
+    const found = await current(path, context)
+    if (found.before === undefined) throw new Error(`${path} does not exist; use write to create it`)
+
+    const count = found.before.split(oldText).length - 1
+    if (!oldText || count === 0) throw new Error(`old_text was not found in ${path}`)
+    if (count > 1) throw new Error(`old_text appears ${count} times in ${path}; include more lines to make it unique`)
+    const change = { ...found, after: found.before.replace(oldText, () => String(input.new_text)) }
+    return { request: { tool: "edit", change }, verdict: { kind: "ask" }, perform: () => apply(change, context) }
+  },
+}

package/src/tools/index.ts

@@ -0,0 +1,83 @@
+// Tools the model may call. Each one is plain data plus a function.
+import type { ToolCall } from "../conversation"
+import { gitAvailable } from "../memory"
+import type { CommandRules, Verdict } from "../policy"
+import { sandboxAvailable } from "../sandbox"
+import { bash } from "./bash"
+import { board } from "./board"
+import type { Change } from "./change"
+import { edit } from "./edit"
+import { read } from "./read"
+import { remember } from "./remember"
+import { write } from "./write"
+
+export type { Change }
+
+// What the user is asked to approve.
+export type ApprovalRequest = { tool: string } & ({ change: Change } | { command: string })
+
+// Lives as long as a chat: where the tools may reach, what the model has read, the user's rules,
+// where memory is kept, and the screen that asks for approval or tells what the rules decided.
+export type ToolContext = {
+  workspace: string
+  // memory.md and persona.md, which remember measures before proposing a fact.
+  memory: string
+  persona: string
+  // Where the boards of projects are kept.
+  boards: string
+  seen: Map<string, string>
+  rules: CommandRules
+  approve(request: ApprovalRequest): Promise<boolean>
+  notice(request: ApprovalRequest, verdict: Verdict): void
+}
+
+// An action is fully planned before anything happens, so that the user approves exactly what will be done.
+// The verdict says whether the user's rules already decided it.
+export type Action = { request: ApprovalRequest; verdict: Verdict; perform(): Promise<string> }
+
+type Common = {
+  name: string
+  description: string
+  // JSON Schema of the arguments.
+  parameters: object
+}
+
+// A look needs no approval: it reads, proposes as remember does, or keeps hagumi's own notes as board does.
+// An act is planned first and performed only once the user approves it.
+export type Tool =
+  | (Common & { kind: "look"; run(input: Record<string, unknown>, context: ToolContext): Promise<string> })
+  | (Common & { kind: "act"; plan(input: Record<string, unknown>, context: ToolContext): Promise<Action> })
+
+export type ToolResult = { ok: boolean; output: string }
+
+// bash is offered only where it can run sandboxed, and remember only where git can keep the history of
+// what is remembered. The list never changes within a session.
+export const tools: Tool[] = [read, write, edit, ...(sandboxAvailable ? [bash] : []), ...(gitAvailable ? [remember] : []), board]
+
+const outputLimit = 20_000
+
+// Runs one call. Whatever goes wrong becomes the result the model reads, so that it can correct itself.
+export async function runTool(call: ToolCall, context: ToolContext): Promise<ToolResult> {
+  const tool = tools.find((candidate) => candidate.name === call.name)
+  if (!tool) return { ok: false, output: `Unknown tool: ${call.name}` }
+  try {
+    const input = JSON.parse(call.arguments || "{}")
+    if (tool.kind === "look") return { ok: true, output: truncate(await tool.run(input, context)) }
+
+    const { request, verdict, perform } = await tool.plan(input, context)
+    if (verdict.kind === "deny") {
+      context.notice(request, verdict)
+      return { ok: false, output: `The user's settings forbid this (rule: ${verdict.rule}).` }
+    }
+    if (verdict.kind === "allow") context.notice(request, verdict)
+    else if (!(await context.approve(request))) return { ok: false, output: "The user declined this." }
+    return { ok: true, output: truncate(await perform()) }
+  } catch (error) {
+    return { ok: false, output: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+function truncate(output: string): string {
+  if (output.length <= outputLimit) return output
+  return `${output.slice(0, outputLimit)}\n[truncated: ${output.length - outputLimit} more characters]`
+}

package/src/tools/read.ts

@@ -0,0 +1,29 @@
+import { readdir, stat } from "node:fs/promises"
+import type { Tool } from "."
+import { fingerprint, resolveInWorkspace } from "./workspace"
+
+export const read: Tool = {
+  name: "read",
+  kind: "look",
+  description:
+    "Read a text file, or list a directory, inside the working directory. Paths are relative to the working directory.",
+  parameters: {
+    type: "object",
+    properties: { path: { type: "string", description: "A file or directory, such as src/cli.ts or ." } },
+    required: ["path"],
+    additionalProperties: false,
+  },
+  async run(input, context) {
+    const target = await resolveInWorkspace(String(input.path), context.workspace)
+    if ((await stat(target)).isDirectory()) {
+      const entries = await readdir(target, { withFileTypes: true })
+      return entries
+        .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
+        .sort()
+        .join("\n")
+    }
+    const content = await Bun.file(target).text()
+    context.seen.set(target, fingerprint(content))
+    return content
+  },
+}

package/src/tools/remember.ts

@@ -0,0 +1,39 @@
+import type { Tool } from "."
+import { factFrom, fits, placeFor } from "../memory"
+
+// Only proposes: after the reply, hagumi keeps what came from the user's own words, and asks the user about
+// anything that may come from a file or a command output (docs/design/memory.md).
+export const remember: Tool = {
+  name: "remember",
+  kind: "look",
+  description: [
+    "Propose a fact worth remembering in later sessions: about the user, such as what they prefer and how they like to work; about the project, such as how it is built and tested; or about yourself, that is how you speak, such as your first person, tone, sentence endings, humor, and how you carry a conversation.",
+    "Write one short statement of fact, not an instruction, in the language you are speaking. About yourself, write a lasting habit rather than something that happened once; how you speak is about yourself even when the user asks for it.",
+    "Memory is shared by every project, so hagumi marks a fact about the project with the project's name.",
+    "After your reply, hagumi keeps it, asking the user first when it may come from a file or a command output; it takes effect from the next session.",
+    "Never propose secrets such as keys or passwords, or what matters only for the task at hand.",
+  ].join(" "),
+  parameters: {
+    type: "object",
+    properties: {
+      about: { type: "string", enum: ["user", "project", "self"], description: "Whom or what the fact is about." },
+      fact: { type: "string", description: 'One fact, such as "The user prefers short replies" or "The tests run with bun test".' },
+    },
+    required: ["about", "fact"],
+    additionalProperties: false,
+  },
+  async run(input, context) {
+    if (input.about !== "user" && input.about !== "project" && input.about !== "self") {
+      throw new Error('Say what the fact is about: "user", "project", or "self".')
+    }
+    const fact = factFrom(input, context.workspace)
+    if (!fact) throw new Error("Write the fact to remember.")
+    const { path, limit } = placeFor(input.about, context)
+    if (!(await fits(fact, path, limit))) {
+      throw new Error(
+        `${input.about === "self" ? "Your persona" : "Memory"} is full (up to ${limit} characters). Tell the user, who can tidy it by hand; \`hagumi memory\` shows where it is.`,
+      )
+    }
+    return "Proposed. After your reply, hagumi keeps it, asking the user first when it may come from a file or a command output."
+  },
+}

package/src/tools/workspace.ts

@@ -0,0 +1,41 @@
+import { lstatSync } from "node:fs"
+import { realpath } from "node:fs/promises"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
+import { storageHome } from "../app"
+
+// Resolves a path the model gave and refuses anything outside the workspace, symbolic links included.
+// A path that does not exist yet is resolved through its nearest existing directory.
+export async function resolveInWorkspace(path: string, workspace: string): Promise<string> {
+  const root = await realpath(workspace)
+  const target = await canonical(resolve(root, path))
+  const fromRoot = relative(root, target)
+  if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+    throw new Error(`${path} is outside the working directory`)
+  }
+  const fromStorage = relative(await canonical(storageHome), target)
+  if (fromStorage !== ".." && !fromStorage.startsWith(`..${sep}`) && !isAbsolute(fromStorage)) {
+    throw new Error(`${path} is inside hagumi's storage directory`)
+  }
+  return target
+}
+
+async function canonical(path: string): Promise<string> {
+  let existing = path
+  while (!exists(existing)) existing = dirname(existing)
+  return join(await realpath(existing), relative(existing, path))
+}
+
+// lstat, so that a symbolic link counts as existing even when what it points to does not.
+function exists(path: string): boolean {
+  try {
+    lstatSync(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// What the model last saw of a file, to notice changes made since.
+export function fingerprint(content: string): string {
+  return String(Bun.hash(content))
+}

package/src/tools/write.ts

@@ -0,0 +1,23 @@
+import type { Tool } from "."
+import { apply, current } from "./change"
+
+export const write: Tool = {
+  name: "write",
+  kind: "act",
+  description:
+    "Create a file, or replace a whole file, inside the working directory. Read an existing file first. " +
+    "For small changes to an existing file, prefer edit. The user approves every change.",
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Relative to the working directory." },
+      content: { type: "string", description: "The complete new content of the file." },
+    },
+    required: ["path", "content"],
+    additionalProperties: false,
+  },
+  async plan(input, context) {
+    const change = { ...(await current(String(input.path), context)), after: String(input.content) }
+    return { request: { tool: "write", change }, verdict: { kind: "ask" }, perform: () => apply(change, context) }
+  },
+}

package/src/wire/chat.ts

@@ -0,0 +1,64 @@
+// The OpenAI-compatible Chat Completions API, spoken by most providers.
+import type { Message, ToolCall } from "../conversation"
+import { failure, type Wire } from "."
+
+type ToolCallDelta = { index: number; id?: string; function?: { name?: string; arguments?: string } }
+type ChatChunk = { choices?: { delta?: { content?: string | null; tool_calls?: ToolCallDelta[] } }[] }
+
+export const chat: Wire = {
+  path: "/chat/completions",
+  auth: (key) => ({ Authorization: `Bearer ${key}` }),
+  request: ({ model, system, conversation, tools }) => ({
+    model,
+    messages: [{ role: "system", content: system }, ...conversation.map(chatMessage)],
+    tools: tools.map(({ name, description, parameters }) => ({
+      type: "function",
+      function: { name, description, parameters },
+    })),
+    stream: true,
+    stream_options: { include_usage: true },
+  }),
+  async *read(events) {
+    let text = ""
+    // A tool call arrives in pieces, matched by index.
+    const toolCalls: ToolCall[] = []
+    for await (const event of events) {
+      if ("error" in event) throw failure(event)
+      const delta = (event as ChatChunk).choices?.[0]?.delta
+      if (delta?.content) {
+        text += delta.content
+        yield { kind: "text", delta: delta.content }
+      }
+      for (const piece of delta?.tool_calls ?? []) {
+        const call = (toolCalls[piece.index] ??= { id: "", name: "", arguments: "" })
+        call.id ||= piece.id ?? ""
+        call.name += piece.function?.name ?? ""
+        call.arguments += piece.function?.arguments ?? ""
+      }
+    }
+    return { text, toolCalls: toolCalls.filter(Boolean) }
+  },
+}
+
+function chatMessage(message: Message): object {
+  switch (message.role) {
+    case "user":
+      return { role: "user", content: message.text }
+    case "assistant":
+      return {
+        role: "assistant",
+        content: message.text || null,
+        ...(message.toolCalls.length > 0
+          ? {
+              tool_calls: message.toolCalls.map((call) => ({
+                id: call.id,
+                type: "function",
+                function: { name: call.name, arguments: call.arguments },
+              })),
+            }
+          : {}),
+      }
+    case "tool":
+      return { role: "tool", tool_call_id: message.callId, content: message.output }
+  }
+}

package/src/wire/index.ts

@@ -0,0 +1,38 @@
+// A wire is one shape of model API. Providers differ in data; only wires and auth need code.
+import type { Message, ToolCall, TurnEvent } from "../conversation"
+import type { Tool } from "../tools"
+import { chat } from "./chat"
+import { messages } from "./messages"
+import { responses } from "./responses"
+
+export type StreamEvent = Record<string, unknown>
+
+export type Reply = { text: string; toolCalls: ToolCall[] }
+
+export type RequestParts = {
+  model: string
+  system: string
+  conversation: Message[]
+  tools: Pick<Tool, "name" | "description" | "parameters">[]
+}
+
+export type Wire = {
+  path: string
+  // How the credential travels: these headers are redacted in the log.
+  auth(key: string): Record<string, string>
+  request(parts: RequestParts): object
+  // Streams the reply text as it arrives, then returns the whole reply.
+  read(events: AsyncIterable<StreamEvent>): AsyncGenerator<Extract<TurnEvent, { kind: "text" }>, Reply>
+}
+
+export const wires = {
+  "openai-responses": responses,
+  "openai-chat": chat,
+  "anthropic-messages": messages,
+} satisfies Record<string, Wire>
+
+export type WireName = keyof typeof wires
+
+export function failure(event: StreamEvent): Error {
+  return new Error(`The response failed: ${JSON.stringify(event)}`)
+}

package/src/wire/messages.ts

@@ -0,0 +1,75 @@
+// The Anthropic Messages API.
+import type { Message, ToolCall } from "../conversation"
+import { failure, type Wire } from "."
+
+type Block = { type?: string; id?: string; name?: string }
+type Delta = { type?: string; text?: string; partial_json?: string }
+type AnthropicMessage = { role: "user" | "assistant"; content: string | object[] }
+
+export const messages: Wire = {
+  path: "/messages",
+  auth: (key) => ({ "x-api-key": key, "anthropic-version": "2023-06-01" }),
+  request: ({ model, system, conversation, tools }) => ({
+    model,
+    // Required by this API; generous enough for a conversational reply.
+    max_tokens: 8192,
+    system,
+    messages: anthropicMessages(conversation),
+    tools: tools.map(({ name, description, parameters }) => ({ name, description, input_schema: parameters })),
+    stream: true,
+  }),
+  async *read(events) {
+    let text = ""
+    // A tool call arrives as a block whose JSON input streams in pieces.
+    const toolCalls = new Map<number, ToolCall>()
+    for await (const event of events) {
+      if (event.type === "error") throw failure(event)
+      const block = event.content_block as Block | undefined
+      const delta = event.delta as Delta | undefined
+      if (event.type === "content_block_start" && block?.type === "tool_use") {
+        toolCalls.set(Number(event.index), { id: String(block.id), name: String(block.name), arguments: "" })
+      }
+      if (event.type !== "content_block_delta") continue
+      if (delta?.type === "text_delta" && delta.text) {
+        text += delta.text
+        yield { kind: "text", delta: delta.text }
+      }
+      const call = toolCalls.get(Number(event.index))
+      if (delta?.type === "input_json_delta" && call) call.arguments += delta.partial_json ?? ""
+    }
+    return { text, toolCalls: [...toolCalls.values()] }
+  },
+}
+
+function anthropicMessages(conversation: Message[]): AnthropicMessage[] {
+  const result: AnthropicMessage[] = []
+  for (const message of conversation) {
+    if (message.role === "user") {
+      result.push({ role: "user", content: message.text })
+    } else if (message.role === "assistant") {
+      result.push({
+        role: "assistant",
+        content: [
+          ...(message.text ? [{ type: "text", text: message.text }] : []),
+          ...message.toolCalls.map((call) => ({ type: "tool_use", id: call.id, name: call.name, input: inputOf(call) })),
+        ],
+      })
+    } else {
+      // The results of one step travel together in a single user message.
+      const block = { type: "tool_result", tool_use_id: message.callId, content: message.output }
+      const last = result.at(-1)
+      if (last?.role === "user" && Array.isArray(last.content)) last.content.push(block)
+      else result.push({ role: "user", content: [block] })
+    }
+  }
+  return result
+}
+
+// The model's arguments are kept as text; this API wants them as an object again.
+function inputOf(call: ToolCall): object {
+  try {
+    return JSON.parse(call.arguments || "{}")
+  } catch {
+    return {}
+  }
+}

package/src/wire/responses.ts

@@ -0,0 +1,56 @@
+// The OpenAI Responses API.
+import type { Message, ToolCall } from "../conversation"
+import { failure, type Wire } from "."
+
+type OutputItem = { type?: string; call_id?: string; name?: string; arguments?: string }
+
+export const responses: Wire = {
+  path: "/responses",
+  auth: (key) => ({ Authorization: `Bearer ${key}` }),
+  // Each request carries the conversation rebuilt from the local log. `store: false` asks the provider
+  // not to store responses for later API retrieval; other retention follows the provider's policies.
+  request: ({ model, system, conversation, tools }) => ({
+    model,
+    instructions: system,
+    input: conversation.flatMap(inputItems),
+    tools: tools.map(({ name, description, parameters }) => ({ type: "function", name, description, parameters })),
+    stream: true,
+    store: false,
+  }),
+  async *read(events) {
+    let text = ""
+    const toolCalls: ToolCall[] = []
+    for await (const event of events) {
+      if (event.type === "error" || event.type === "response.failed") throw failure(event)
+      if (event.type === "response.output_text.delta") {
+        const delta = String(event.delta)
+        text += delta
+        yield { kind: "text", delta }
+      }
+      const item = event.item as OutputItem | undefined
+      if (event.type === "response.output_item.done" && item?.type === "function_call") {
+        toolCalls.push({ id: String(item.call_id), name: String(item.name), arguments: item.arguments ?? "" })
+      }
+    }
+    return { text, toolCalls }
+  },
+}
+
+function inputItems(message: Message): object[] {
+  switch (message.role) {
+    case "user":
+      return [{ role: "user", content: [{ type: "input_text", text: message.text }] }]
+    case "assistant":
+      return [
+        ...(message.text ? [{ role: "assistant", content: [{ type: "output_text", text: message.text }] }] : []),
+        ...message.toolCalls.map((call) => ({
+          type: "function_call",
+          call_id: call.id,
+          name: call.name,
+          arguments: call.arguments,
+        })),
+      ]
+    case "tool":
+      return [{ type: "function_call_output", call_id: message.callId, output: message.output }]
+  }
+}

package/src/wire/stream.ts

@@ -0,0 +1,57 @@
+import type { SessionLog } from "../log"
+import type { StreamEvent } from "."
+
+const secretHeaders = ["authorization", "x-api-key"]
+
+// Sends one request and yields its stream events. Both are logged as they are, except for secrets.
+export async function* streamEvents(options: {
+  url: string
+  headers: Record<string, string>
+  body: object
+  log: SessionLog
+}): AsyncGenerator<StreamEvent> {
+  const { url, headers, body, log } = options
+  await log.append({ kind: "request", url, headers: redact(headers), body })
+
+  const response = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) })
+  if (!response.ok || !response.body) {
+    const text = await response.text()
+    await log.append({ kind: "response_error", status: response.status, body: text })
+    throw new Error(`POST ${url} failed: ${response.status} ${text}`)
+  }
+
+  for await (const event of serverSentEvents(response.body)) {
+    await log.append({ kind: "response_event", event })
+    yield event
+  }
+}
+
+export function redact(headers: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(headers).map(([name, value]) => [
+      name,
+      secretHeaders.includes(name.toLowerCase()) ? "<redacted>" : value,
+    ]),
+  )
+}
+
+// Turns a text/event-stream body into the JSON payload of each event's `data:` lines.
+export async function* serverSentEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<StreamEvent> {
+  const decoder = new TextDecoder()
+  let buffer = ""
+  for await (const chunk of body) {
+    buffer += decoder.decode(chunk, { stream: true }).replaceAll("\r\n", "\n")
+    let end = buffer.indexOf("\n\n")
+    while (end !== -1) {
+      const data = buffer
+        .slice(0, end)
+        .split("\n")
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trimStart())
+        .join("\n")
+      buffer = buffer.slice(end + 2)
+      if (data && data !== "[DONE]") yield JSON.parse(data) as StreamEvent
+      end = buffer.indexOf("\n\n")
+    }
+  }
+}

package/src/workspaces.ts

@@ -0,0 +1,75 @@
+// hagumi new: a fresh place for each chat, named by the local date and time under the workspaces of the settings,
+// such as ~/hagumi-work/2026-10-12/13-24 (docs/concept.md §7.4). It starts as a git repository, which the model
+// could not create from inside its sandbox. A place left empty can be tidied away.
+import { existsSync } from "node:fs"
+import { mkdir, readdir, rm, rmdir } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { gitAvailable } from "./memory"
+
+// The names hagumi new gives; nothing else under the workspaces is ever tidied away.
+const day = /^\d{4}-\d{2}-\d{2}$/
+const time = /^\d{2}-\d{2}(-\d+)?$/
+
+// "~" in the settings stands for the home directory.
+export function expandHome(path: string): string {
+  return path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path
+}
+
+// mkdir fails on a directory that exists, so two starts in the same minute never share one: the second gets 13-24-2.
+export async function newWorkspace(root: string, now = new Date()): Promise<string> {
+  const pad = (n: number) => String(n).padStart(2, "0")
+  const today = join(expandHome(root), `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`)
+  const minute = `${pad(now.getHours())}-${pad(now.getMinutes())}`
+  await mkdir(today, { recursive: true })
+  for (let n = 1; ; n++) {
+    const dir = join(today, n === 1 ? minute : `${minute}-${n}`)
+    try {
+      await mkdir(dir)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") continue
+      throw error
+    }
+    if (gitAvailable) {
+      const git = Bun.spawn(["git", "init", "--quiet"], { cwd: dir, stdin: "ignore", stdout: "ignore", stderr: "pipe" })
+      if ((await git.exited) !== 0) throw new Error(`git init: ${(await new Response(git.stderr).text()).trim()}`)
+    }
+    return dir
+  }
+}
+
+// Empty: nothing but a repository without a single commit. Anything else keeps a place, even a hidden file,
+// or commits whose files have been deleted since.
+export async function isEmpty(dir: string): Promise<boolean> {
+  const entries = await readdir(dir)
+  if (entries.length === 0) return true
+  if (entries.length > 1 || entries[0] !== ".git" || !gitAvailable) return false
+  const head = Bun.spawn(["git", "rev-parse", "--verify", "--quiet", "HEAD"], { cwd: dir, stdin: "ignore", stdout: "ignore", stderr: "ignore" })
+  return (await head.exited) !== 0
+}
+
+// The empty places hagumi new made under the workspaces, oldest first.
+export async function emptyWorkspaces(root: string): Promise<string[]> {
+  const base = expandHome(root)
+  if (!existsSync(base)) return []
+  const found: string[] = []
+  for (const date of await subdirectories(base, day)) {
+    for (const minute of await subdirectories(join(base, date), time)) {
+      if (await isEmpty(join(base, date, minute))) found.push(join(base, date, minute))
+    }
+  }
+  return found
+}
+
+// Removes a place only if it is still empty, and its day once nothing else is left there.
+export async function tidy(dir: string): Promise<boolean> {
+  if (!(await isEmpty(dir))) return false
+  await rm(dir, { recursive: true })
+  if ((await readdir(dirname(dir))).length === 0) await rmdir(dirname(dir))
+  return true
+}
+
+async function subdirectories(dir: string, name: RegExp): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+  return entries.flatMap((entry) => (entry.isDirectory() && name.test(entry.name) ? [entry.name] : [])).sort()
+}