pi-incarnate 0.1.0 → 0.2.0

package/src/character-bundle.ts

@@ -0,0 +1,330 @@
+import { link, lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+
+import {
+  installPersonalAvatar,
+  prepareAvatarContent,
+  prepareAvatarImport,
+  type PreparedAvatarImport,
+} from "./avatar-manager.ts";
+import {
+  CharacterEditError,
+  createPersonalCharacter,
+} from "./character-editor.ts";
+import { FORM_MAX_BYTES, readFormDraft, savePersonalForm } from "./form-editor.ts";
+import { parseFormDeclarations } from "./forms.ts";
+import { isCharacterId, loadCharacter, parseCharacterCard, type Character } from "./character-loader.ts";
+
+export const CHARACTER_BUNDLE_FORMAT = "pi-incarnate-character";
+export const CHARACTER_BUNDLE_VERSION = 1;
+export const CHARACTER_BUNDLE_SUFFIX = ".pi-character.json";
+export const CHARACTER_BUNDLE_MAX_BYTES = 1024 * 1024;
+const CHARACTER_CARD_MAX_BYTES = 512 * 1024;
+const CHARACTER_BUNDLE_MAX_FILES = 66;
+
+interface CharacterBundleFileV1 {
+  path: string;
+  content: string;
+}
+
+interface CharacterBundleDocumentV1 {
+  format: typeof CHARACTER_BUNDLE_FORMAT;
+  version: typeof CHARACTER_BUNDLE_VERSION;
+  id: string;
+  files: CharacterBundleFileV1[];
+}
+
+export interface PreparedCharacterBundle {
+  id: string;
+  name: string;
+  card: string;
+  avatar?: PreparedAvatarImport;
+  forms: Array<{ path: string; content: string }>;
+}
+
+export interface CharacterBundleSummary {
+  id: string;
+  name: string;
+  avatarIncluded: boolean;
+  formsIncluded: number;
+  formsDeclared: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function byteLength(value: string): number {
+  return Buffer.byteLength(value, "utf8");
+}
+
+function normalizeDeclaredFormPath(value: string): string {
+  if (
+    !value ||
+    value.includes("\\") ||
+    value.includes("\0") ||
+    isAbsolute(value) ||
+    posix.isAbsolute(value) ||
+    /^[a-zA-Z]:/.test(value)
+  ) {
+    throw new CharacterEditError(`Invalid character bundle path: ${value}`);
+  }
+  const normalized = posix.normalize(value);
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    throw new CharacterEditError(`Invalid character bundle path: ${value}`);
+  }
+  return normalized;
+}
+
+function normalizePortablePath(value: string): string {
+  const normalized = normalizeDeclaredFormPath(value);
+  if (normalized !== value) throw new CharacterEditError(`Invalid character bundle path: ${value}`);
+  return normalized;
+}
+
+function portableRelativePath(root: string, target: string): string {
+  const value = relative(root, target).split(sep).join("/");
+  return normalizePortablePath(value);
+}
+
+function assertBundleTarget(path: string): void {
+  if (!path.toLowerCase().endsWith(CHARACTER_BUNDLE_SUFFIX)) {
+    throw new CharacterEditError(`Character bundle must end in ${CHARACTER_BUNDLE_SUFFIX}`);
+  }
+}
+
+async function assertMissing(path: string, message: string): Promise<void> {
+  try {
+    await lstat(path);
+    throw new CharacterEditError(message);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+async function readRegularUtf8(path: string, maximumBytes: number, label: string): Promise<string> {
+  let bytes: Buffer;
+  try {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      throw new CharacterEditError(`${label} must be a regular file: ${path}`);
+    }
+    if (info.size > maximumBytes) throw new CharacterEditError(`${label} exceeds the ${maximumBytes}-byte limit`);
+    bytes = await readFile(path);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    throw new CharacterEditError(`Cannot read ${label.toLowerCase()}: ${path}`);
+  }
+  if (bytes.byteLength > maximumBytes) throw new CharacterEditError(`${label} exceeds the ${maximumBytes}-byte limit`);
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new CharacterEditError(`${label} is not valid UTF-8: ${path}`);
+  }
+}
+
+async function bundleDocument(character: Character): Promise<{ document: CharacterBundleDocumentV1; summary: CharacterBundleSummary }> {
+  const card = `${character.markdown.trimEnd()}\n`;
+  if (byteLength(card) > CHARACTER_CARD_MAX_BYTES) {
+    throw new CharacterEditError(`CHARACTER.md exceeds the ${CHARACTER_CARD_MAX_BYTES}-byte bundle limit`);
+  }
+  const files: CharacterBundleFileV1[] = [{ path: "CHARACTER.md", content: card }];
+
+  let avatarIncluded = false;
+  for (const filename of ["avatar.ansi", "avatar.txt"] as const) {
+    const avatarPath = join(character.directory, filename);
+    try {
+      await lstat(avatarPath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw new CharacterEditError(`Cannot inspect avatar for export: ${avatarPath}`);
+    }
+    const avatar = await prepareAvatarImport(avatarPath);
+    files.push({ path: avatar.filename, content: avatar.content });
+    avatarIncluded = true;
+    break;
+  }
+
+  const includedForms = new Set<string>();
+  for (const form of character.forms) {
+    if (form.status !== "available") continue;
+    const draft = await readFormDraft(character.directory, form.declaredPath, form.label);
+    if (!draft.exists) continue;
+    const path = portableRelativePath(character.directory, draft.path);
+    if (includedForms.has(path)) continue;
+    includedForms.add(path);
+    files.push({ path, content: draft.content });
+  }
+
+  if (files.length > CHARACTER_BUNDLE_MAX_FILES) {
+    throw new CharacterEditError(`Character bundle exceeds the ${CHARACTER_BUNDLE_MAX_FILES}-file limit`);
+  }
+  const document: CharacterBundleDocumentV1 = {
+    format: CHARACTER_BUNDLE_FORMAT,
+    version: CHARACTER_BUNDLE_VERSION,
+    id: character.id,
+    files,
+  };
+  const encoded = `${JSON.stringify(document, null, 2)}\n`;
+  if (byteLength(encoded) > CHARACTER_BUNDLE_MAX_BYTES) {
+    throw new CharacterEditError(`Character bundle exceeds the ${CHARACTER_BUNDLE_MAX_BYTES}-byte limit`);
+  }
+  return {
+    document,
+    summary: {
+      id: character.id,
+      name: character.name,
+      avatarIncluded,
+      formsIncluded: includedForms.size,
+      formsDeclared: character.forms.length,
+    },
+  };
+}
+
+export async function writeCharacterBundle(
+  character: Character,
+  targetPath: string,
+): Promise<CharacterBundleSummary> {
+  assertBundleTarget(targetPath);
+  const requestedTarget = resolve(targetPath);
+  const parent = dirname(requestedTarget);
+  let canonicalParent: string;
+  try {
+    const info = await lstat(parent);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      throw new CharacterEditError(`Bundle destination parent must be a real directory: ${parent}`);
+    }
+    canonicalParent = await realpath(parent);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    throw new CharacterEditError(`Cannot access bundle destination directory: ${parent}`);
+  }
+  const target = join(canonicalParent, basename(requestedTarget));
+  await assertMissing(target, `Character bundle already exists: ${target}`);
+  const { document, summary } = await bundleDocument(character);
+  const temporaryPath = join(canonicalParent, `.incarnate-export-${crypto.randomUUID()}.tmp`);
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(document, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    await link(temporaryPath, target);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      throw new CharacterEditError(`Character bundle already exists: ${target}`);
+    }
+    if (error instanceof CharacterEditError) throw error;
+    throw new CharacterEditError(`Cannot write character bundle: ${target}`);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+  return summary;
+}
+
+function validateBundleDocument(value: unknown): PreparedCharacterBundle {
+  if (!isRecord(value) || value.format !== CHARACTER_BUNDLE_FORMAT || value.version !== CHARACTER_BUNDLE_VERSION) {
+    throw new CharacterEditError("Unsupported character bundle format or version");
+  }
+  if (typeof value.id !== "string" || !isCharacterId(value.id)) {
+    throw new CharacterEditError("Character bundle has an invalid id");
+  }
+  if (!Array.isArray(value.files) || value.files.length === 0 || value.files.length > CHARACTER_BUNDLE_MAX_FILES) {
+    throw new CharacterEditError(`Character bundle must contain 1-${CHARACTER_BUNDLE_MAX_FILES} files`);
+  }
+
+  const files = new Map<string, string>();
+  let contentBytes = 0;
+  for (const entry of value.files) {
+    if (!isRecord(entry) || typeof entry.path !== "string" || typeof entry.content !== "string") {
+      throw new CharacterEditError("Character bundle contains an invalid file entry");
+    }
+    const path = normalizePortablePath(entry.path);
+    if (files.has(path)) throw new CharacterEditError(`Character bundle contains a duplicate path: ${path}`);
+    contentBytes += byteLength(entry.content);
+    if (contentBytes > CHARACTER_BUNDLE_MAX_BYTES) {
+      throw new CharacterEditError(`Character bundle content exceeds the ${CHARACTER_BUNDLE_MAX_BYTES}-byte limit`);
+    }
+    files.set(path, entry.content);
+  }
+
+  const card = files.get("CHARACTER.md");
+  if (card === undefined) throw new CharacterEditError("Character bundle is missing CHARACTER.md");
+  if (byteLength(card) > CHARACTER_CARD_MAX_BYTES) {
+    throw new CharacterEditError(`CHARACTER.md exceeds the ${CHARACTER_CARD_MAX_BYTES}-byte bundle limit`);
+  }
+  const parsed = parseCharacterCard(card, "CHARACTER.md");
+  const allowedForms = new Set<string>();
+  for (const declaration of parseFormDeclarations(card)) {
+    try {
+      const path = normalizeDeclaredFormPath(declaration.declaredPath);
+      if (extname(path).toLowerCase() === ".md" && path !== "CHARACTER.md") allowedForms.add(path);
+    } catch {
+      // Invalid declarations remain unavailable after import and cannot authorize bundled files.
+    }
+  }
+
+  let avatar: PreparedAvatarImport | undefined;
+  const forms: Array<{ path: string; content: string }> = [];
+  for (const [path, content] of files) {
+    if (path === "CHARACTER.md") continue;
+    if (path === "avatar.ansi" || path === "avatar.txt") {
+      if (avatar) throw new CharacterEditError("Character bundle may contain only one avatar file");
+      avatar = prepareAvatarContent(path, content);
+      continue;
+    }
+    if (!allowedForms.has(path)) {
+      throw new CharacterEditError(`Character bundle contains an undeclared file: ${path}`);
+    }
+    if (byteLength(content) > FORM_MAX_BYTES) {
+      throw new CharacterEditError(`Form exceeds the ${FORM_MAX_BYTES}-byte limit: ${path}`);
+    }
+    forms.push({ path, content });
+  }
+  return { id: value.id, name: parsed.name, card, avatar, forms };
+}
+
+export async function prepareCharacterBundleImport(sourcePath: string): Promise<PreparedCharacterBundle> {
+  assertBundleTarget(sourcePath);
+  const content = await readRegularUtf8(sourcePath, CHARACTER_BUNDLE_MAX_BYTES, "Character bundle");
+  let document: unknown;
+  try {
+    document = JSON.parse(content);
+  } catch {
+    throw new CharacterEditError("Character bundle is not valid JSON");
+  }
+  return validateBundleDocument(document);
+}
+
+export async function installCharacterBundle(
+  personalRoot: string,
+  bundle: PreparedCharacterBundle,
+): Promise<Character> {
+  const validated = validateBundleDocument({
+    format: CHARACTER_BUNDLE_FORMAT,
+    version: CHARACTER_BUNDLE_VERSION,
+    id: bundle.id,
+    files: [
+      { path: "CHARACTER.md", content: bundle.card },
+      ...(bundle.avatar ? [{ path: bundle.avatar.filename, content: bundle.avatar.content }] : []),
+      ...bundle.forms.map((form) => ({ path: form.path, content: form.content })),
+    ],
+  });
+  await mkdir(personalRoot, { recursive: true });
+  const canonicalRoot = await realpath(personalRoot);
+  const target = join(canonicalRoot, validated.id);
+  await assertMissing(target, `A personal character already exists: ${validated.id}`);
+  const stagingRoot = await mkdtemp(join(canonicalRoot, ".incarnate-import-"));
+  try {
+    await createPersonalCharacter(stagingRoot, validated.id, validated.card);
+    for (const form of validated.forms) {
+      await savePersonalForm(stagingRoot, validated.id, form.path, form.content);
+    }
+    if (validated.avatar) await installPersonalAvatar(stagingRoot, validated.id, validated.avatar);
+    const staged = await loadCharacter(stagingRoot, validated.id);
+    await rename(staged.directory, target);
+    return await loadCharacter(canonicalRoot, validated.id);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    throw new CharacterEditError(`Cannot install character bundle: ${error instanceof Error ? error.message : "unknown error"}`);
+  } finally {
+    await rm(stagingRoot, { recursive: true, force: true });
+  }
+}

package/src/character-catalog.ts

@@ -0,0 +1,69 @@
+import { lstat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+import {
+  discoverCharacters,
+  loadCharacter,
+  type Character,
+  type CharacterIssue,
+} from "./character-loader.ts";
+
+export type CharacterSource = "personal" | "built-in";
+
+export interface CharacterLocations {
+  builtInRoot: string;
+  personalRoot?: string;
+}
+
+export interface CharacterCatalogEntry {
+  character: Character;
+  source: CharacterSource;
+}
+
+export interface CharacterCatalog {
+  entries: CharacterCatalogEntry[];
+  issues: CharacterIssue[];
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function discoverCharacterCatalog(locations: CharacterLocations): Promise<CharacterCatalog> {
+  const roots: Array<{ root: string; source: CharacterSource }> = [];
+  if (locations.personalRoot) roots.push({ root: locations.personalRoot, source: "personal" });
+  roots.push({ root: locations.builtInRoot, source: "built-in" });
+
+  const entries: CharacterCatalogEntry[] = [];
+  const issues: CharacterIssue[] = [];
+  const seen = new Set<string>();
+  for (const { root, source } of roots) {
+    const discovery = await discoverCharacters(root);
+    issues.push(...discovery.issues);
+    for (const character of discovery.characters) {
+      if (seen.has(character.id)) continue;
+      seen.add(character.id);
+      entries.push({ character, source });
+    }
+  }
+  entries.sort((left, right) => left.character.id.localeCompare(right.character.id));
+  return { entries, issues };
+}
+
+export async function loadCatalogCharacter(locations: CharacterLocations, id: string): Promise<CharacterCatalogEntry> {
+  if (locations.personalRoot && (await pathExists(join(locations.personalRoot, id)))) {
+    return { character: await loadCharacter(locations.personalRoot, id), source: "personal" };
+  }
+  return { character: await loadCharacter(locations.builtInRoot, id), source: "built-in" };
+}
+
+export function characterSource(character: Character, locations: CharacterLocations): CharacterSource {
+  if (locations.personalRoot && dirname(character.directory) === resolve(locations.personalRoot)) return "personal";
+  return "built-in";
+}

package/src/character-editor.ts

@@ -0,0 +1,199 @@
+import { constants } from "node:fs";
+import { copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+import {
+  CharacterLoadError,
+  isCharacterId,
+  loadCharacter,
+  parseCharacterCard,
+  type Character,
+} from "./character-loader.ts";
+
+export class CharacterEditError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CharacterEditError";
+  }
+}
+
+function isWithin(parent: string, child: string): boolean {
+  const pathFromParent = relative(parent, child);
+  return pathFromParent === "" || (!pathFromParent.startsWith(`..${sep}`) && pathFromParent !== "..");
+}
+
+function normalizeForSave(markdown: string): string {
+  return `${markdown.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trim()}\n`;
+}
+
+function assertValidCard(markdown: string, cardPath: string): string {
+  try {
+    parseCharacterCard(markdown, cardPath);
+  } catch (error) {
+    if (error instanceof CharacterLoadError) throw new CharacterEditError(error.message);
+    throw error;
+  }
+  return normalizeForSave(markdown);
+}
+
+export function createCharacterTemplate(name: string): string {
+  return `# ${name}
+
+## Identity
+
+描述角色是谁、来自何处、与用户的关系，以及对自身世界观的理解。
+
+## Personality
+
+描述核心性格、价值偏好、优点、缺点和敏感点。
+
+## Speech Style
+
+描述称呼、口癖、句式、语气、常用词、禁用词，并可加入示例对话。
+
+## Behavior
+
+描述角色如何表达赞同、质疑、关心、兴奋、失望和道歉，以及必须遵守的边界。
+
+## Current Mood
+
+Default: normal
+
+### normal
+
+保持角色的常态表达方式。
+`;
+}
+
+async function ensureNewTarget(personalRoot: string, id: string): Promise<string> {
+  if (!isCharacterId(id)) throw new CharacterEditError(`Invalid character id: ${id}`);
+  await mkdir(personalRoot, { recursive: true });
+  const canonicalRoot = await realpath(personalRoot);
+  const target = join(canonicalRoot, id);
+  try {
+    await lstat(target);
+    throw new CharacterEditError(`A personal character already exists: ${id}`);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  return target;
+}
+
+async function copyRegularTree(source: string, target: string): Promise<void> {
+  await mkdir(target);
+  for (const entry of await readdir(source, { withFileTypes: true })) {
+    const sourcePath = join(source, entry.name);
+    const targetPath = join(target, entry.name);
+    if (entry.isSymbolicLink()) throw new CharacterEditError(`Cannot copy symbolic link: ${sourcePath}`);
+    if (entry.isDirectory()) {
+      await copyRegularTree(sourcePath, targetPath);
+    } else if (entry.isFile()) {
+      await copyFile(sourcePath, targetPath, constants.COPYFILE_EXCL);
+    } else {
+      throw new CharacterEditError(`Cannot copy non-regular file: ${sourcePath}`);
+    }
+  }
+}
+
+export async function createPersonalCharacter(
+  personalRoot: string,
+  id: string,
+  markdown: string,
+): Promise<Character> {
+  const target = await ensureNewTarget(personalRoot, id);
+  const normalized = assertValidCard(markdown, join(target, "CHARACTER.md"));
+  const stagingRoot = await mkdtemp(join(await realpath(personalRoot), ".incarnate-create-"));
+  try {
+    const stagingCharacter = join(stagingRoot, id);
+    await mkdir(stagingCharacter);
+    await writeFile(join(stagingCharacter, "CHARACTER.md"), normalized, { encoding: "utf8", flag: "wx" });
+    await loadCharacter(stagingRoot, id);
+    await rename(stagingCharacter, target);
+  } finally {
+    await rm(stagingRoot, { recursive: true, force: true });
+  }
+  return await loadCharacter(personalRoot, id);
+}
+
+export async function resolvePersonalDirectory(personalRoot: string, id: string): Promise<string> {
+  if (!isCharacterId(id)) throw new CharacterEditError(`Invalid character id: ${id}`);
+  const canonicalRoot = await realpath(personalRoot);
+  const candidate = join(canonicalRoot, id);
+  const info = await lstat(candidate).catch(() => undefined);
+  if (!info?.isDirectory() || info.isSymbolicLink()) {
+    throw new CharacterEditError(`Personal character directory is missing or invalid: ${id}`);
+  }
+  const canonicalDirectory = await realpath(candidate);
+  if (!isWithin(canonicalRoot, canonicalDirectory) || dirname(canonicalDirectory) !== canonicalRoot) {
+    throw new CharacterEditError(`Personal character directory escapes its root: ${id}`);
+  }
+  return canonicalDirectory;
+}
+
+export async function updatePersonalCharacter(
+  personalRoot: string,
+  id: string,
+  markdown: string,
+): Promise<Character> {
+  const directory = await resolvePersonalDirectory(personalRoot, id);
+  const cardPath = join(directory, "CHARACTER.md");
+  const normalized = assertValidCard(markdown, cardPath);
+  const temporaryPath = join(directory, `.CHARACTER.${crypto.randomUUID()}.tmp`);
+  try {
+    await writeFile(temporaryPath, normalized, { encoding: "utf8", flag: "wx" });
+    await rename(temporaryPath, cardPath);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+  return await loadCharacter(personalRoot, id);
+}
+
+export async function readPersonalCharacterDraft(personalRoot: string, id: string): Promise<string> {
+  const directory = await resolvePersonalDirectory(personalRoot, id);
+  const cardPath = join(directory, "CHARACTER.md");
+  let buffer: Buffer;
+  try {
+    const cardInfo = await lstat(cardPath);
+    if (!cardInfo.isFile() || cardInfo.isSymbolicLink()) {
+      throw new CharacterEditError(`Personal CHARACTER.md must be a regular file: ${id}`);
+    }
+    buffer = await readFile(cardPath);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    throw new CharacterEditError(`Cannot read personal character card: ${id}`);
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+  } catch {
+    throw new CharacterEditError(`CHARACTER.md is not valid UTF-8: ${cardPath}`);
+  }
+}
+
+export async function createPersonalOverride(
+  personalRoot: string,
+  source: Character,
+  markdown: string,
+): Promise<Character> {
+  const target = await ensureNewTarget(personalRoot, source.id);
+  const normalized = assertValidCard(markdown, join(target, "CHARACTER.md"));
+  const stagingRoot = await mkdtemp(join(await realpath(personalRoot), ".incarnate-copy-"));
+  try {
+    const stagingCharacter = join(stagingRoot, source.id);
+    await copyRegularTree(source.directory, stagingCharacter);
+    await writeFile(join(stagingCharacter, "CHARACTER.md"), normalized, "utf8");
+    await loadCharacter(stagingRoot, source.id);
+    await rename(stagingCharacter, target);
+  } finally {
+    await rm(stagingRoot, { recursive: true, force: true });
+  }
+  return await loadCharacter(personalRoot, source.id);
+}
+
+export async function readCharacterCard(character: Character): Promise<string> {
+  return await readFile(character.cardPath, "utf8");
+}
+
+export function isPersonalCharacter(character: Character, personalRoot: string): boolean {
+  return dirname(character.directory) === resolve(personalRoot);
+}

package/src/character-lifecycle.ts

@@ -0,0 +1,94 @@
+import { lstat, mkdir, realpath, rename } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+import { CharacterEditError, resolvePersonalDirectory } from "./character-editor.ts";
+import { discoverCharacters, isCharacterId, loadCharacter, type CharacterDiscovery, type Character } from "./character-loader.ts";
+
+export function characterArchiveRoot(personalRoot: string): string {
+  return join(dirname(resolve(personalRoot)), "archive");
+}
+
+async function ensureRealRoot(root: string): Promise<string> {
+  await mkdir(root, { recursive: true });
+  const canonicalRoot = await resolveExistingRoot(root);
+  if (!canonicalRoot) throw new CharacterEditError(`Character root disappeared: ${root}`);
+  return canonicalRoot;
+}
+
+async function resolveExistingRoot(root: string): Promise<string | undefined> {
+  let info;
+  try {
+    info = await lstat(root);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new CharacterEditError(`Character root must be a real directory: ${root}`);
+  }
+  return await realpath(root);
+}
+
+async function assertMissing(path: string, message: string): Promise<void> {
+  try {
+    await lstat(path);
+    throw new CharacterEditError(message);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+export async function renamePersonalCharacter(
+  personalRoot: string,
+  currentId: string,
+  nextId: string,
+): Promise<Character> {
+  if (!isCharacterId(nextId)) throw new CharacterEditError(`Invalid character id: ${nextId}`);
+  if (currentId === nextId) throw new CharacterEditError("The new character id is unchanged");
+  const source = await resolvePersonalDirectory(personalRoot, currentId);
+  const canonicalRoot = await realpath(personalRoot);
+  const target = join(canonicalRoot, nextId);
+  await assertMissing(target, `A personal character already exists: ${nextId}`);
+
+  await rename(source, target);
+  try {
+    return await loadCharacter(canonicalRoot, nextId);
+  } catch (error) {
+    await rename(target, source).catch(() => undefined);
+    throw new CharacterEditError(`Cannot rename character: ${error instanceof Error ? error.message : "unknown error"}`);
+  }
+}
+
+export async function archivePersonalCharacter(personalRoot: string, id: string): Promise<string> {
+  const source = await resolvePersonalDirectory(personalRoot, id);
+  await loadCharacter(personalRoot, id);
+  const archiveRoot = await ensureRealRoot(characterArchiveRoot(personalRoot));
+  const target = join(archiveRoot, id);
+  await assertMissing(target, `An archived character already exists: ${id}`);
+  await rename(source, target);
+  return target;
+}
+
+export async function discoverArchivedCharacters(personalRoot: string): Promise<CharacterDiscovery> {
+  const archiveRoot = await resolveExistingRoot(characterArchiveRoot(personalRoot));
+  return archiveRoot ? await discoverCharacters(archiveRoot) : { characters: [], issues: [] };
+}
+
+export async function restoreArchivedCharacter(personalRoot: string, id: string): Promise<Character> {
+  if (!isCharacterId(id)) throw new CharacterEditError(`Invalid character id: ${id}`);
+  const archiveRoot = await ensureRealRoot(characterArchiveRoot(personalRoot));
+  const archived = await loadCharacter(archiveRoot, id);
+  await mkdir(personalRoot, { recursive: true });
+  const canonicalPersonalRoot = await realpath(personalRoot);
+  const target = join(canonicalPersonalRoot, id);
+  await assertMissing(target, `A personal character already exists: ${id}`);
+
+  await rename(archived.directory, target);
+  try {
+    return await loadCharacter(canonicalPersonalRoot, id);
+  } catch (error) {
+    await rename(target, archived.directory).catch(() => undefined);
+    throw new CharacterEditError(`Cannot restore character: ${error instanceof Error ? error.message : "unknown error"}`);
+  }
+}