pi-incarnate 0.1.0 → 0.3.0

package/src/commands.ts

@@ -1,26 +1,36 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
-import { CharacterLoadError, discoverCharacters, loadCharacter } from "./character-loader.ts";
+import {
+  characterSource,
+  discoverCharacterCatalog,
+  loadCatalogCharacter,
+  type CharacterLocations,
+} from "./character-catalog.ts";
+import { CharacterLoadError } from "./character-loader.ts";
+import { openIncarnateMenu } from "./menu.ts";
+import type { AvatarMode } from "./session-state.ts";
 import type { IncarnateSessionState } from "./session-state.ts";
 
 export interface IncarnateCommandDependencies {
   charactersRoot: string;
+  personalCharactersRoot?: string;
   state: IncarnateSessionState;
   onStateChange?: (ctx: ExtensionCommandContext) => Promise<void> | void;
 }
 
 const USAGE =
-  "Usage: /incarnate list | use <character-id> | off | status | mood <preset> | avatar on|off";
+  "Usage: /incarnate list | use <character-id> | off | status | mood <preset> | avatar auto|full|compact|off";
 
 function notifyError(ctx: ExtensionCommandContext, message: string): void {
   ctx.ui.notify(message, "error");
 }
 
 export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: IncarnateCommandDependencies): void {
-  const { charactersRoot, state, onStateChange } = dependencies;
+  const { charactersRoot, personalCharactersRoot, state, onStateChange } = dependencies;
+  const locations: CharacterLocations = { builtInRoot: charactersRoot, personalRoot: personalCharactersRoot };
 
   pi.registerCommand("incarnate", {
-    description: "List, enable, disable, or inspect character personas",
+    description: "Open the character menu or manage personas with subcommands",
     getArgumentCompletions: async (prefix) => {
       const [subcommand = "", argument = ""] = prefix.trimStart().split(/\s+/, 2);
       if (!prefix.trimStart().includes(" ")) {
@@ -29,7 +39,7 @@ export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: Incarna
           .map((value) => ({ value, label: value }));
       }
       if (subcommand === "avatar") {
-        const matches = ["on", "off"]
+        const matches = ["auto", "full", "compact", "off", "on"]
           .filter((value) => value.startsWith(argument))
           .map((value) => ({ value: `avatar ${value}`, label: value }));
         return matches.length > 0 ? matches : null;
@@ -41,22 +51,31 @@ export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: Incarna
         return matches.length > 0 ? matches : null;
       }
       if (subcommand !== "use") return null;
-      const { characters } = await discoverCharacters(charactersRoot);
-      const matches = characters
-        .filter((character) => character.id.startsWith(argument))
-        .map((character) => ({ value: `use ${character.id}`, label: character.id, description: character.name }));
+      const { entries } = await discoverCharacterCatalog(locations);
+      const matches = entries
+        .filter(({ character }) => character.id.startsWith(argument))
+        .map(({ character }) => ({ value: `use ${character.id}`, label: character.id, description: character.name }));
       return matches.length > 0 ? matches : null;
     },
     handler: async (args, ctx) => {
       const [subcommand = "", id, ...extra] = args.trim().split(/\s+/).filter(Boolean);
 
+      if (!subcommand) {
+        if (ctx.hasUI) {
+          await openIncarnateMenu(ctx, { locations, state, onStateChange });
+        } else {
+          ctx.ui.notify(USAGE, "info");
+        }
+        return;
+      }
+
       if (subcommand === "list" && !id) {
-        const { characters, issues } = await discoverCharacters(charactersRoot);
-        if (characters.length === 0) {
-          ctx.ui.notify(`No valid characters found in ${charactersRoot}`, "warning");
+        const { entries, issues } = await discoverCharacterCatalog(locations);
+        if (entries.length === 0) {
+          ctx.ui.notify("No valid characters found", "warning");
         } else {
-          const list = characters
-            .map((character) => `${character.id} — ${character.name}${state.activeCharacter?.id === character.id ? " (active)" : ""}`)
+          const list = entries
+            .map(({ character, source }) => `${character.id} — ${character.name}${state.activeCharacter?.id === character.id ? " (active)" : ""} [${source}]`)
             .join("\n");
           ctx.ui.notify(list, "info");
         }
@@ -68,7 +87,7 @@ export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: Incarna
 
       if (subcommand === "use" && id && extra.length === 0) {
         try {
-          const character = await loadCharacter(charactersRoot, id);
+          const { character } = await loadCatalogCharacter(locations, id);
           state.activate(character);
           await onStateChange?.(ctx);
           ctx.ui.notify(`Character enabled: ${character.name} (${character.id})`, "info");
@@ -91,8 +110,8 @@ export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: Incarna
         const active = state.activeCharacter;
         ctx.ui.notify(
           active
-            ? `Active character: ${active.name} (${active.id})\nMood: ${state.currentMood ?? "none"}\nAvatar: ${state.avatarEnabled ? "on" : "off"}\nForms: ${active.forms.filter((form) => form.status === "available").length}/${active.forms.length} available\nCard: ${active.cardPath}`
-            : `Character mode: off\nAvatar: ${state.avatarEnabled ? "on" : "off"}`,
+            ? `Active character: ${active.name} (${active.id})\nSource: ${characterSource(active, locations)}\nMood: ${state.currentMood ?? "none"}\nAvatar: ${state.avatarMode}\nForms: ${active.forms.filter((form) => form.status === "available").length}/${active.forms.length} available\nCard: ${active.cardPath}`
+            : `Character mode: off\nAvatar: ${state.avatarMode}`,
           "info",
         );
         return;
@@ -115,10 +134,16 @@ export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: Incarna
         return;
       }
 
-      if (subcommand === "avatar" && (id === "on" || id === "off") && extra.length === 0) {
-        state.setAvatarEnabled(id === "on");
+      if (
+        subcommand === "avatar" &&
+        id &&
+        ["auto", "full", "compact", "off", "on"].includes(id) &&
+        extra.length === 0
+      ) {
+        const mode: AvatarMode = id === "on" ? "auto" : (id as AvatarMode);
+        state.setAvatarMode(mode);
         await onStateChange?.(ctx);
-        ctx.ui.notify(`Avatar: ${id}`, "info");
+        ctx.ui.notify(`Avatar: ${mode}`, "info");
         return;
       }
 

package/src/form-editor.ts

@@ -0,0 +1,115 @@
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
+
+import { CharacterEditError, resolvePersonalDirectory } from "./character-editor.ts";
+
+export const FORM_MAX_BYTES = 256 * 1024;
+
+export interface FormDraft {
+  path: string;
+  content: string;
+  exists: boolean;
+}
+
+function isWithin(parent: string, child: string): boolean {
+  const pathFromParent = relative(parent, child);
+  return pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`) && !isAbsolute(pathFromParent);
+}
+
+function formTarget(characterDirectory: string, declaredPath: string): string {
+  if (!declaredPath || isAbsolute(declaredPath) || extname(declaredPath).toLowerCase() !== ".md") {
+    throw new CharacterEditError("Editable form paths must be relative .md files");
+  }
+  const target = resolve(characterDirectory, declaredPath);
+  if (!isWithin(characterDirectory, target) || target === characterDirectory) {
+    throw new CharacterEditError(`Form path escapes the character directory: ${declaredPath}`);
+  }
+  return target;
+}
+
+function formTemplate(label: string): string {
+  return `# ${label}\n\n在这里记录希望角色按需读取的偏好信息。\n`;
+}
+
+async function inspectExistingForm(characterDirectory: string, target: string): Promise<Buffer | undefined> {
+  let info;
+  try {
+    info = await lstat(target);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new CharacterEditError(`Cannot inspect form file: ${target}`);
+  }
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new CharacterEditError(`Form must be a regular file, not a symbolic link: ${target}`);
+  }
+  const canonicalTarget = await realpath(target);
+  if (!isWithin(characterDirectory, canonicalTarget)) {
+    throw new CharacterEditError(`Form path escapes the character directory: ${target}`);
+  }
+  if (info.size > FORM_MAX_BYTES) throw new CharacterEditError(`Form exceeds the ${FORM_MAX_BYTES}-byte editor limit: ${target}`);
+  const bytes = await readFile(canonicalTarget);
+  if (bytes.byteLength > FORM_MAX_BYTES) throw new CharacterEditError(`Form exceeds the ${FORM_MAX_BYTES}-byte editor limit: ${target}`);
+  return bytes;
+}
+
+export async function readFormDraft(
+  characterDirectory: string,
+  declaredPath: string,
+  label: string,
+): Promise<FormDraft> {
+  const canonicalDirectory = await realpath(characterDirectory);
+  const target = formTarget(canonicalDirectory, declaredPath);
+  const bytes = await inspectExistingForm(canonicalDirectory, target);
+  if (!bytes) return { path: target, content: formTemplate(label), exists: false };
+  try {
+    return { path: target, content: new TextDecoder("utf-8", { fatal: true }).decode(bytes), exists: true };
+  } catch {
+    throw new CharacterEditError(`Form is not valid UTF-8: ${target}`);
+  }
+}
+
+async function ensureSafeParent(characterDirectory: string, target: string): Promise<string> {
+  const relativeParent = relative(characterDirectory, dirname(target));
+  let current = characterDirectory;
+  for (const segment of relativeParent.split(sep).filter((value) => value && value !== ".")) {
+    current = resolve(current, segment);
+    try {
+      await mkdir(current);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+    const info = await lstat(current);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      throw new CharacterEditError(`Form parent must be a regular directory: ${current}`);
+    }
+    const canonicalCurrent = await realpath(current);
+    if (!isWithin(characterDirectory, canonicalCurrent)) {
+      throw new CharacterEditError(`Form parent escapes the character directory: ${current}`);
+    }
+  }
+  return current;
+}
+
+export async function savePersonalForm(
+  personalRoot: string,
+  id: string,
+  declaredPath: string,
+  content: string,
+): Promise<string> {
+  const characterDirectory = await resolvePersonalDirectory(personalRoot, id);
+  const target = formTarget(characterDirectory, declaredPath);
+  await inspectExistingForm(characterDirectory, target);
+  const parent = await ensureSafeParent(characterDirectory, target);
+  const normalized = `${content.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trimEnd()}\n`;
+  if (Buffer.byteLength(normalized, "utf8") > FORM_MAX_BYTES) {
+    throw new CharacterEditError(`Form exceeds the ${FORM_MAX_BYTES}-byte editor limit: ${target}`);
+  }
+  const temporaryPath = resolve(parent, `.form-${crypto.randomUUID()}.tmp`);
+  try {
+    await writeFile(temporaryPath, normalized, { encoding: "utf8", flag: "wx" });
+    await rename(temporaryPath, target);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+  return target;
+}

package/src/markdown.ts

@@ -56,3 +56,15 @@ export function extractLevelTwoSections(markdown: string): MarkdownSection[] {
 export function findLevelTwoSection(markdown: string, name: string): string | undefined {
   return extractLevelTwoSections(markdown).find((section) => section.name.toLowerCase() === name.toLowerCase())?.content;
 }
+
+export function removeLevelTwoSection(markdown: string, name: string): string {
+  const { lines, headings } = findHeadings(markdown, 2);
+  const excluded = new Set<number>();
+  headings.forEach((heading, index) => {
+    if (heading.name.toLowerCase() !== name.toLowerCase()) return;
+    const end = headings[index + 1]?.line ?? lines.length;
+    for (let line = heading.line; line < end; line += 1) excluded.add(line);
+  });
+  if (excluded.size === 0) return markdown;
+  return lines.filter((_line, index) => !excluded.has(index)).join("\n").trim();
+}