pi-incarnate 0.1.0 → 0.3.0

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"}`);
+  }
+}

package/src/character-loader.ts

@@ -41,6 +41,13 @@ export interface CharacterDiscovery {
   issues: CharacterIssue[];
 }
 
+export interface ParsedCharacterCard {
+  markdown: string;
+  name: string;
+  sections: Readonly<Record<RequiredSection, string>>;
+  mood: MoodConfig;
+}
+
 export class CharacterLoadError extends Error {
   readonly code: CharacterIssueCode;
   readonly path: string;
@@ -94,6 +101,19 @@ function parseCard(markdown: string, cardPath: string): Pick<Character, "name" |
   };
 }
 
+export function parseCharacterCard(markdown: string, cardPath = "CHARACTER.md"): ParsedCharacterCard {
+  const normalized = markdown.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trim();
+  const parsed = parseCard(normalized, cardPath);
+  let mood: MoodConfig;
+  try {
+    mood = parseMoodConfig(normalized);
+  } catch (error) {
+    const message = error instanceof MoodConfigError ? error.message : "Invalid Current Mood section";
+    throw new CharacterLoadError("invalid-card", message, cardPath);
+  }
+  return { markdown: normalized, mood, ...parsed };
+}
+
 export function isCharacterId(value: string): boolean {
   return CHARACTER_ID_PATTERN.test(value);
 }
@@ -123,33 +143,37 @@ export async function loadCharacter(charactersRoot: string, id: string): Promise
   }
 
   const cardPath = join(characterDirectory, "CHARACTER.md");
+  let canonicalCardPath: string;
   try {
     if (!(await stat(characterDirectory)).isDirectory()) {
       throw new CharacterLoadError("invalid-directory", `Character path is not a directory: ${id}`, characterDirectory);
     }
+    const cardInfo = await lstat(cardPath);
+    if (!cardInfo.isFile() || cardInfo.isSymbolicLink()) {
+      throw new CharacterLoadError("outside-root", `CHARACTER.md must be a regular file: ${id}`, cardPath);
+    }
+    canonicalCardPath = await realpath(cardPath);
+    if (!isWithin(characterDirectory, canonicalCardPath) || dirname(canonicalCardPath) !== characterDirectory) {
+      throw new CharacterLoadError("outside-root", `CHARACTER.md escapes the character directory: ${id}`, cardPath);
+    }
   } catch (error) {
     if (error instanceof CharacterLoadError) throw error;
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new CharacterLoadError("missing-card", `Missing or unreadable CHARACTER.md for: ${id}`, cardPath);
+    }
     throw new CharacterLoadError("unreadable", `Cannot inspect character directory: ${id}`, characterDirectory);
   }
 
   let buffer: Buffer;
   try {
-    buffer = await readFile(cardPath);
+    buffer = await readFile(canonicalCardPath);
   } catch {
     throw new CharacterLoadError("missing-card", `Missing or unreadable CHARACTER.md for: ${id}`, cardPath);
   }
 
-  const markdown = decodeUtf8(buffer, cardPath).replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trim();
-  const parsed = parseCard(markdown, cardPath);
-  let mood: MoodConfig;
-  try {
-    mood = parseMoodConfig(markdown);
-  } catch (error) {
-    const message = error instanceof MoodConfigError ? error.message : "Invalid Current Mood section";
-    throw new CharacterLoadError("invalid-card", message, cardPath);
-  }
-  const forms = await resolveFormReferences(characterDirectory, markdown);
-  return { id, directory: characterDirectory, cardPath, markdown, mood, forms, ...parsed };
+  const parsed = parseCharacterCard(decodeUtf8(buffer, cardPath), cardPath);
+  const forms = await resolveFormReferences(characterDirectory, parsed.markdown);
+  return { id, directory: characterDirectory, cardPath, forms, ...parsed };
 }
 
 export async function discoverCharacters(charactersRoot: string): Promise<CharacterDiscovery> {

package/src/character-section-editor.ts

@@ -0,0 +1,120 @@
+import { CharacterEditError } from "./character-editor.ts";
+
+export const GUIDED_CHARACTER_SECTIONS = [
+  "Identity",
+  "Personality",
+  "Speech Style",
+  "Behavior",
+  "Current Mood",
+  "Tools and Forms",
+] as const;
+
+export type GuidedCharacterSection = (typeof GUIDED_CHARACTER_SECTIONS)[number];
+
+export interface CharacterSectionDraft {
+  content: string;
+  exists: boolean;
+}
+
+interface HeadingLocation {
+  level: number;
+  line: number;
+  name: string;
+}
+
+function normalizedLines(markdown: string): string[] {
+  return markdown.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").split("\n");
+}
+
+function headings(lines: readonly string[]): HeadingLocation[] {
+  const locations: HeadingLocation[] = [];
+  let fence: { marker: string; length: number } | undefined;
+  lines.forEach((line, index) => {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      const marker = fenceMatch[1]![0]!;
+      if (!fence) fence = { marker, length: fenceMatch[1]!.length };
+      else if (fence.marker === marker && fenceMatch[1]!.length >= fence.length) fence = undefined;
+      return;
+    }
+    if (fence) return;
+    const match = line.match(/^(#{1,6})(?!#)\s+(.+?)(?:\s+#+)?\s*$/);
+    if (match) locations.push({ level: match[1]!.length, line: index, name: match[2]!.trim() });
+  });
+  return locations;
+}
+
+function normalizeBody(content: string): string {
+  return content.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trim();
+}
+
+function finish(lines: readonly string[]): string {
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function sectionLocation(lines: readonly string[], name: string): { heading: HeadingLocation; endLine: number } | undefined {
+  const levelTwo = headings(lines).filter((heading) => heading.level === 2);
+  const matches = levelTwo.filter((heading) => heading.name.toLowerCase() === name.toLowerCase());
+  if (matches.length > 1) throw new CharacterEditError(`Character card contains duplicate sections: ${name}`);
+  const heading = matches[0];
+  if (!heading) return undefined;
+  const next = levelTwo.find((candidate) => candidate.line > heading.line);
+  return { heading, endLine: next?.line ?? lines.length };
+}
+
+export function readCharacterSection(markdown: string, name: GuidedCharacterSection): CharacterSectionDraft {
+  const lines = normalizedLines(markdown);
+  const location = sectionLocation(lines, name);
+  if (!location) return { content: "", exists: false };
+  return {
+    content: lines.slice(location.heading.line + 1, location.endLine).join("\n").trim(),
+    exists: true,
+  };
+}
+
+export function updateCharacterSection(
+  markdown: string,
+  name: GuidedCharacterSection,
+  content: string,
+): string {
+  const lines = normalizedLines(markdown);
+  const location = sectionLocation(lines, name);
+  const body = normalizeBody(content);
+  if (headings(body.split("\n")).some((heading) => heading.level <= 2)) {
+    throw new CharacterEditError("Section content cannot contain level-one or level-two headings; use the complete card editor");
+  }
+  if (!location) {
+    const existing = lines.join("\n").trimEnd();
+    return `${existing}\n\n## ${name}\n\n${body}${body ? "\n" : ""}`;
+  }
+  const replacement = body ? ["", ...body.split("\n"), ""] : [""];
+  return finish([
+    ...lines.slice(0, location.heading.line + 1),
+    ...replacement,
+    ...lines.slice(location.endLine),
+  ]);
+}
+
+export function updateCharacterName(markdown: string, name: string): string {
+  const normalizedName = name.trim().replace(/\s*[\r\n]+\s*/g, " ");
+  if (!normalizedName) throw new CharacterEditError("Character name must not be empty");
+  if (normalizedName.length > 120) throw new CharacterEditError("Character name must not exceed 120 characters");
+  if (/\s#+$/.test(normalizedName)) {
+    throw new CharacterEditError("Character name must not end with Markdown closing hashes");
+  }
+  const lines = normalizedLines(markdown);
+  const firstHeading = headings(lines).find((heading) => heading.level === 1);
+  if (!firstHeading) throw new CharacterEditError("CHARACTER.md must contain a level-one character name");
+  lines[firstHeading.line] = `# ${normalizedName}`;
+  return finish(lines);
+}
+
+export function sectionStarter(name: GuidedCharacterSection): string {
+  if (name === "Current Mood") {
+    return "Default: normal\n\n### normal\n\n保持角色的常态表达方式。";
+  }
+  if (name === "Tools and Forms") {
+    return "- 偏好表名称：`forms/preferences.md`";
+  }
+  return "";
+}