Skip to content
Python
6.4 KB
Raw Blame
/** Explicit, separately-confirmed deletion of the One Memory Home.
 *
 * The contract is strict and deliberately awkward, because this is the one
 * action that destroys user memory:
 *   - It is a separate command (`memhub delete-data`), never folded into
 *     `uninstall`. Uninstall keeps the data; this is the only thing that
 *     removes it.
 *   - Preview first, then two independent confirmations: `--yes` alone is not
 *     enough, the caller must also repeat the exact data directory with
 *     `--confirm <path>`.
 *   - Refuse to act unless the target is provably a One Memory Home: it must be
 *     an absolute, non-root, non-home directory that contains the runtime's own
 *     artifacts. An unknown or empty directory is never deleted.
 *   - A live Runtime must be stopped first; deletion while Core holds the
 *     SQLite file would corrupt or silently skip data.
 */

import { lstat, readdir, rm, rmdir } from "node:fs/promises";
import path from "node:path";

export interface DataDeletionPlan {
  schema_version: 1;
  product: string;
  command: "delete-data";
  state: "preview" | "blocked";
  data_dir: string;
  /** Files/dirs that would be removed, for a legible preview. */
  entries: string[];
  bytes: number;
  code?: string;
  reason?: string;
  next_step?: string;
}

export interface DataDeletionReceipt {
  schema_version: 1;
  product: string;
  command: "delete-data";
  state: "deleted";
  data_dir: string;
  removed_entries: string[];
}

/** Markers that prove a directory is a One Memory Home, not an arbitrary path.
 * At least one must exist; a lone directory name is not evidence. */
const HOME_MARKERS = [
  "one-memory.sqlite3",
  "runtime-service.json",
  "host-permissions",
  "hy-memory",
  "integrations",
  "logs",
] as const;

async function directoryInfo(target: string) {
  const info = await lstat(target).catch(() => null);
  return info;
}

export async function planDataDeletion(options: {
  dataDir: string;
  home: string;
  runtimeRunning: boolean;
}): Promise<DataDeletionPlan> {
  const base = (): Pick<
    DataDeletionPlan,
    "schema_version" | "product" | "command" | "entries" | "bytes"
  > => ({
    schema_version: 1,
    product: "memhub",
    command: "delete-data",
    entries: [],
    bytes: 0,
  });
  const blocked = (
    code: string,
    reason: string,
    nextStep: string,
  ): DataDeletionPlan => ({
    ...base(),
    state: "blocked",
    data_dir: options.dataDir,
    code,
    reason,
    next_step: nextStep,
  });
  const target = options.dataDir;
  if (!path.isAbsolute(target) || /[\0\r\n]/.test(target)) {
    return blocked(
      "data_dir_unusable",
      "数据目录必须是绝对且无换行的路径。",
      "传入 --data-dir 的绝对路径后重试。",
    );
  }
  const resolved = path.resolve(target);
  if (resolved === path.parse(resolved).root) {
    return blocked(
      "data_dir_refused",
      "拒绝删除文件系统根目录。",
      "指向具体的 One Memory Home 后重试。",
    );
  }
  if (resolved === path.resolve(options.home)) {
    return blocked(
      "data_dir_refused",
      "拒绝删除用户主目录本身。",
      "指向 One Memory Home(默认 ~/.one-memory)后重试。",
    );
  }
  if (options.runtimeRunning) {
    return blocked(
      "runtime_still_running",
      "Runtime 仍在运行,Core 正持有数据库文件。",
      "先运行 memhub stop 停止 Runtime,再执行 delete-data。",
    );
  }
  const info = await directoryInfo(resolved);
  if (info === null) {
    return blocked(
      "data_dir_missing",
      "数据目录不存在。",
      "确认 --data-dir 后重试;无需删除。",
    );
  }
  if (!info.isDirectory() || info.isSymbolicLink()) {
    return blocked(
      "data_dir_refused",
      "数据目录不是普通目录(或是符号链接)。",
      "指向真实的 One Memory Home 目录后重试。",
    );
  }
  const names = await readdir(resolved).catch(() => [] as string[]);
  const markers = names.filter((name) =>
    (HOME_MARKERS as readonly string[]).includes(name),
  );
  if (markers.length === 0) {
    return blocked(
      "not_a_one_memory_home",
      "目录里没有 One Memory 运行产物,拒绝删除未知目录。",
      "确认 --data-dir 指向真正的 One Memory Home。",
    );
  }
  const entries: string[] = [];
  let bytes = 0;
  for (const name of names) {
    const entry = path.join(resolved, name);
    const entryInfo = await lstat(entry).catch(() => null);
    if (entryInfo === null) continue;
    entries.push(entry);
    bytes += await approxBytes(entry);
  }
  entries.sort();
  return { ...base(), state: "preview", data_dir: resolved, entries, bytes };
}

export async function applyDataDeletion(
  plan: DataDeletionPlan,
  confirmation: string,
): Promise<DataDeletionReceipt> {
  if (plan.state !== "preview") {
    throw new Error(plan.code ?? "data_deletion_blocked");
  }
  // The second confirmation must name the exact directory from the preview, so
  // a stale or copy-pasted `--yes` cannot trigger deletion of a different path.
  if (path.resolve(confirmation) !== path.resolve(plan.data_dir)) {
    throw new Error("data_deletion_confirmation_mismatch");
  }
  const removed: string[] = [];
  for (const entry of plan.entries) {
    // Re-check containment at apply time: a plan is data and can be stale.
    if (path.dirname(path.resolve(entry)) !== path.resolve(plan.data_dir)) {
      throw new Error("data_deletion_path_unsafe");
    }
    await rm(entry, { recursive: true, force: true });
    removed.push(entry);
  }
  // Remove the now-empty home itself, but only if it is genuinely empty.
  const remaining = await readdir(plan.data_dir).catch(() => null);
  if (remaining !== null && remaining.length === 0) {
    // `rmdir` on an empty directory; never a recursive delete here, so a race
    // that refilled the directory cannot be silently destroyed.
    await rmdir(plan.data_dir).catch(() => undefined);
  }
  return {
    schema_version: 1,
    product: "memhub",
    command: "delete-data",
    state: "deleted",
    data_dir: plan.data_dir,
    removed_entries: removed,
  };
}

async function approxBytes(target: string): Promise<number> {
  const info = await lstat(target).catch(() => null);
  if (info === null) return 0;
  if (info.isFile()) return info.size;
  if (!info.isDirectory()) return 0;
  let total = 0;
  const names = await readdir(target).catch(() => [] as string[]);
  for (const name of names) {
    total += await approxBytes(path.join(target, name));
  }
  return total;
}