@momenttttt/pi-zcode-memory 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@momenttttt/pi-zcode-memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Share ZCode's per-project memory directory from pi (memory_read / memory_write / memory_list)",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "memory",
+    "zcode",
+    "project-memory"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Momenttttt/pi-extension-suite.git",
+    "directory": "packages/pi-zcode-memory"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/zcode-memory.ts"
+    ]
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.."
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/atomic.ts

@@ -0,0 +1,69 @@
+/**
+ * 原子写：同目录临时文件（`O_EXCL`）→ 写入 → fsync → rename；不跟随符号链接。
+ *
+ * 失败就报错让模型重试，不做"open 失败就改用 `O_TRUNC` 直写目标"的降级：那一步会破坏原子性，
+ * 留下一个只写了一半的文件。
+ */
+import { constants } from "node:fs";
+import { lstat, open, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export class SymlinkWriteRefusedError extends Error {
+  constructor(path: string) {
+    super(`Refusing to write through a symbolic link: ${path}. Pass the real target path instead.`);
+    this.name = "SymlinkWriteRefusedError";
+  }
+}
+
+/** 临时文件名：同目录才能保证 rename 是原子的；`.tmp.<pid>.<random>` 避免并发撞名。 */
+function tempPathFor(path: string): string {
+  return join(dirname(path), `.${basenameOf(path)}.tmp.${process.pid}.${randomBytes(6).toString("hex")}`);
+}
+
+function basenameOf(path: string): string {
+  const separator = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return separator < 0 ? path : path.slice(separator + 1);
+}
+
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+
+export async function atomicWriteFile(path: string, content: string): Promise<void> {
+  let existingMode: number | undefined;
+  try {
+    const target = await lstat(path);
+    if (target.isSymbolicLink()) throw new SymlinkWriteRefusedError(path);
+    existingMode = target.mode;
+  } catch (error) {
+    if (!isNoEntryError(error)) throw error;
+  }
+
+  const tempPath = tempPathFor(path);
+  const buffer = Buffer.from(content, "utf8");
+  try {
+    const handle = await open(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NOFOLLOW);
+    try {
+      await handle.writeFile(buffer);
+      if (existingMode !== undefined) {
+        // 原子写会用临时文件的 inode 覆盖目标；先复制原权限，避免抹掉执行位
+        await handle.chmod(existingMode);
+      }
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(tempPath, path);
+  } catch (error) {
+    await unlink(tempPath).catch(() => undefined);
+    throw error;
+  }
+}
+
+function isNoEntryError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}

package/src/bridge.ts

@@ -0,0 +1,57 @@
+/**
+ * 与 pi-read-guard 的读态互通：**发布方**的本地契约。
+ *
+ * 机制选择：`pi.events` 共享事件总线。理由：
+ *   - 两个包都从 pi 拿到同一个总线，不需要新增配置文件契约；
+ *   - 耦合只剩一个字符串 + 一份形状；发布方 `emit`、接收方 `on`，任一方缺席都不报错；
+ *   - 相比"由配置声明的读态提供方"，少一层配置形状与解析规则，收益相同。
+ *
+ * 按 ADR-0001（四个独立包、无内部共享包）与 CODING_STANDARDS 规则 5，这里**刻意重复**
+ * 声明常量与类型，不 import `pi-read-guard`。对齐点见
+ * `packages/pi-read-guard/src/bridge.ts`（接收方）——改形状时两边要一起改。
+ */
+import { createHash } from "node:crypto";
+
+export const READ_STATE_EVENT = "read-guard/file-read";
+
+/** 一次"某记忆文件刚被读过"的登记。 */
+export interface ReadStateEventPayload {
+  /** 绝对路径：发布方与接收方可能不在同一个 cwd 下。 */
+  path: string;
+  /** 读时的文件 mtime（毫秒）。 */
+  mtimeMs: number;
+  sizeBytes: number;
+  /** 完整文本内容的 sha256；截断读时**不带**。 */
+  contentHash?: string;
+  kind: "full" | "ranged" | "truncated";
+}
+
+export interface ReadStatePayloadInput {
+  absolutePath: string;
+  mtimeMs: number;
+  sizeBytes: number;
+  /** 完整正文（未截断时）的 sha256；截断读或拿不到全文时不传。 */
+  contentHash?: string;
+  truncated: boolean;
+}
+
+/**
+ * 生成发布载荷。
+ *
+ * 截断读一律 `kind: "truncated"` 且不带 hash——read-guard 会把它当成"读得不完整"，
+ * 不允许它成为写水位（与内置 `read` 的 `details.truncation` 同一条规则）。
+ */
+export function buildReadStatePayload(input: ReadStatePayloadInput): ReadStateEventPayload {
+  return {
+    path: input.absolutePath,
+    mtimeMs: input.mtimeMs,
+    sizeBytes: input.sizeBytes,
+    kind: input.truncated ? "truncated" : "full",
+    ...(!input.truncated && input.contentHash !== undefined ? { contentHash: input.contentHash } : {}),
+  };
+}
+
+/** 与 read-guard 的 `hashContent` 同构：sha256(utf8 文本原样)。 */
+export function hashMemoryContent(content: string): string {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}

package/src/config.ts

@@ -0,0 +1,88 @@
+/**
+ * 配置读取：全局 `<agent-dir>/extensions/zcode-memory.json` + 项目 `<cwd>/.pi/zcode-memory.json`，
+ * 深合并、防御式解析。形状与另外三个包一致。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface ZcodeMemoryConfig {
+  enabled: boolean;
+  /**
+   * 显式指定记忆目录（最高优先级）。路径算法对不上时（工作区标识、工作区路径写法差异），
+   * 这是唯一可靠的兜底。
+   */
+  dir: string | undefined;
+  /** 是否做索引注入。默认开。
+   *  单独留开关是为了排查"注入内容干扰上下文"一类问题，不面向常规使用。 */
+  injectIndex: boolean;
+}
+
+export const DEFAULT_ZCODE_MEMORY_CONFIG: ZcodeMemoryConfig = {
+  enabled: true,
+  dir: undefined,
+  injectIndex: true,
+};
+
+function readJsonIfExists(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return isPlainObject(parsed) ? parsed : {};
+  } catch {
+    // 配置坏了不能让插件崩，退化成默认值
+    return {};
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** 深合并：只对普通对象递归，数组与标量后写者胜。 */
+export function deepMerge<T extends Record<string, unknown>>(base: T, override: Record<string, unknown>): T {
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const current = result[key];
+    result[key] = isPlainObject(current) && isPlainObject(value) ? deepMerge(current, value) : value;
+  }
+  return result as T;
+}
+
+/** 把外部 JSON 折算成可信配置；非法值一律退回默认值。 */
+export function parseZcodeMemoryConfig(raw: unknown): ZcodeMemoryConfig {
+  if (!isPlainObject(raw)) return { ...DEFAULT_ZCODE_MEMORY_CONFIG };
+  const config = { ...DEFAULT_ZCODE_MEMORY_CONFIG };
+  if (typeof raw.enabled === "boolean") config.enabled = raw.enabled;
+  if (typeof raw.injectIndex === "boolean") config.injectIndex = raw.injectIndex;
+  if (typeof raw.dir === "string" && raw.dir.trim().length > 0) config.dir = raw.dir.trim();
+  return config;
+}
+
+/**
+ * 定位全局配置目录。
+ *
+ * 优先读 pi 自己的环境变量 `PI_CODING_AGENT_DIR`（`pi --help` 列的就是它，pi 内部的
+ * `getAgentDir()` 也认这个），再退回 `~/.pi/agent`。
+ *
+ * 注意别写成 `PI_AGENT_DIR`：那不是 pi 认的名字，设了它 pi 自己的扩展/设置仍然走
+ * `~/.pi/agent`，于是"我们的全局配置"与"pi 的全局资源"会分叉到两个目录。
+ */
+export function resolveAgentDir(env: NodeJS.ProcessEnv = process.env): string {
+  const fromEnv = env.PI_CODING_AGENT_DIR;
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) return fromEnv;
+  return join(homedir(), ".pi", "agent");
+}
+
+export interface LoadConfigOptions {
+  agentDir?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+/** 全局 → 项目，深合并。 */
+export function loadConfig(cwd: string, options: LoadConfigOptions = {}): ZcodeMemoryConfig {
+  const agentDir = options.agentDir ?? resolveAgentDir(options.env ?? process.env);
+  const globalRaw = readJsonIfExists(join(agentDir, "extensions", "zcode-memory.json"));
+  const projectRaw = readJsonIfExists(join(cwd, ".pi", "zcode-memory.json"));
+  return parseZcodeMemoryConfig(deepMerge(globalRaw, projectRaw));
+}

package/src/errors.ts

@@ -0,0 +1,21 @@
+/** 写入路径上的可预期失败；`code` 供扩展折算成工具错误文案。 */
+export type MemoryWriteErrorCode =
+  | "invalid_name"
+  | "exists"
+  | "symlink"
+  | "index_conflict"
+  | "io"
+  | "invalid_input";
+
+export class MemoryWriteError extends Error {
+  readonly code: MemoryWriteErrorCode;
+  /** 给模型的下一步建议；拼进工具错误文案。 */
+  readonly hint?: string;
+
+  constructor(code: MemoryWriteErrorCode, message: string, hint?: string) {
+    super(message);
+    this.name = "MemoryWriteError";
+    this.code = code;
+    if (hint !== undefined) this.hint = hint;
+  }
+}

package/src/frontmatter.ts

@@ -0,0 +1,136 @@
+/**
+ * 事实文件 frontmatter 的解析与生成。
+ *
+ * 解析规则：
+ *   - 只在前 30 行里找 frontmatter：扫描窗口必须有界，否则一个没有 frontmatter 的文件要被
+ *     整份读进来才能判定（列表扫描对每个文件都做一次这件事）；定成 30 是因为读这些文件的
+ *     一侧也只看这么多——闭合行更靠后的文件在两边都算"无描述条目"
+ *   - 首行必须是 `---`，闭合行必须是单独的 `---`
+ *   - YAML 解析失败或结果不是映射 → 视为"无描述条目"，不抛错
+ *   - `type` 取 `metadata.type`，退回顶层 `type`；只认四个枚举值
+ *
+ * 生成规则（设计 §2.2）：只写 `name` / `description` / `metadata.node_type` / `metadata.type`，
+ * **不写** `originSessionId`：那是读文件的一方在缺失时自己补的惰性字段，我们不伪造不属于
+ * 自己的会话 id；也不加自定义键（未知键行为未核实）。
+ */
+import { parse as parseYaml } from "yaml";
+
+import { MEMORY_TYPES, type MemoryType } from "./paths.ts";
+
+/** 扫描窗口：frontmatter 必须在前 30 行内闭合。 */
+export const FRONTMATTER_SCAN_LINES = 30;
+
+export interface MemoryFrontmatter {
+  name?: string;
+  description?: string;
+  type?: MemoryType;
+  /** 缺 frontmatter、闭合行找不到、YAML 坏、或不是映射时为 true。 */
+  malformed: boolean;
+}
+
+export interface MemoryDocument {
+  frontmatter: MemoryFrontmatter;
+  /** frontmatter 之后的正文；没有合法 frontmatter 时是整份文档。 */
+  body: string;
+}
+
+/** 统一 BOM 与行尾：解析与读取共用这一条归一化，后面按行处理都只面对 `\n`。 */
+export function normalizeMemoryText(content: string): string {
+  return content.replace(/^\uFEFF/u, "").replace(/\r\n/gu, "\n");
+}
+
+/** 找 frontmatter 的闭合行下标（在前 `FRONTMATTER_SCAN_LINES` 行内），找不到返回 -1。 */
+function findFrontmatterEnd(lines: readonly string[]): number {
+  const limit = Math.min(lines.length, FRONTMATTER_SCAN_LINES);
+  for (let index = 1; index < limit; index += 1) {
+    if (lines[index] === "---") return index;
+  }
+  return -1;
+}
+
+export function parseMemoryDocument(content: string): MemoryDocument {
+  const normalized = normalizeMemoryText(content);
+  const lines = normalized.split("\n");
+  if (lines[0] !== "---") {
+    return { frontmatter: { malformed: true }, body: normalized };
+  }
+  const end = findFrontmatterEnd(lines);
+  if (end < 0) {
+    return { frontmatter: { malformed: true }, body: normalized };
+  }
+  const body = lines.slice(end + 1).join("\n").replace(/^\n+/u, "");
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(lines.slice(1, end).join("\n"));
+  } catch {
+    return { frontmatter: { malformed: true }, body };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { frontmatter: { malformed: true }, body };
+  }
+  const record = parsed as Record<string, unknown>;
+  const metadata =
+    typeof record.metadata === "object" && record.metadata !== null && !Array.isArray(record.metadata)
+      ? (record.metadata as Record<string, unknown>)
+      : undefined;
+  const typeCandidate = metadata?.type ?? record.type;
+  const frontmatter: MemoryFrontmatter = { malformed: false };
+  if (typeof record.name === "string" && record.name.trim().length > 0) frontmatter.name = record.name.trim();
+  if (typeof record.description === "string" && record.description.length > 0) {
+    frontmatter.description = record.description;
+  }
+  if (typeof typeCandidate === "string" && (MEMORY_TYPES as readonly string[]).includes(typeCandidate)) {
+    frontmatter.type = typeCandidate as MemoryType;
+  }
+  return { frontmatter, body };
+}
+
+export function parseMemoryFrontmatter(content: string): MemoryFrontmatter {
+  return parseMemoryDocument(content).frontmatter;
+}
+
+export interface RenderMemoryFileInput {
+  name: string;
+  description: string;
+  type: MemoryType;
+  body: string;
+}
+
+/**
+ * 生成事实文件全文。
+ *
+ * YAML 标量按需加双引号（YAML 兼容 JSON 引号）：description 里常见的 `:`、`#`、引号都不会
+ * 弄坏解析。name 已由写入层校验成安全字符。
+ */
+export function renderMemoryFile(input: RenderMemoryFileInput): string {
+  const body = input.body.replace(/\r\n/gu, "\n").replace(/\n*$/u, "");
+  const frontmatter = [
+    "---",
+    `name: ${yamlScalar(input.name)}`,
+    `description: ${yamlScalar(input.description)}`,
+    "metadata:",
+    "  node_type: memory",
+    `  type: ${input.type}`,
+    "---",
+  ].join("\n");
+  return body.length > 0 ? `${frontmatter}\n${body}\n` : `${frontmatter}\n`;
+}
+
+const SPECIAL_SCALAR = /^(?:true|false|null|yes|no|on|off|~)$/iu;
+const PLAIN_SCALAR = /^[\p{L}\p{N}][\p{L}\p{N} .,;!?()[\]{}'"\\/&%*+\-=<>@^`|~$_-]*$/u;
+
+/** 需要时才加引号：保持文件可读，同时保证任何合法输入都能被 YAML 解析回原值。 */
+function yamlScalar(value: string): string {
+  const singleLine = value.replace(/\s+/gu, " ").trim();
+  if (
+    singleLine.length > 0 &&
+    PLAIN_SCALAR.test(singleLine) &&
+    !SPECIAL_SCALAR.test(singleLine) &&
+    !/^\d/u.test(singleLine) &&
+    !/:\s/u.test(singleLine) &&
+    !/\s#/u.test(singleLine)
+  ) {
+    return singleLine;
+  }
+  return JSON.stringify(singleLine);
+}

package/src/index-content.ts

@@ -0,0 +1,102 @@
+/**
+ * 注入用的索引格式化。
+ *
+ *   - 剥掉开头 frontmatter、剥掉顶层 HTML 注释、trim
+ *   - 截断上限 200 行 / 25 000 字符，超限追加一条 WARNING
+ *
+ * 不引入 markdown 解析器：逐行扫描就够——代码围栏外、行首以 `<!--` 开头的注释块整块剥掉，
+ * 列表项与段落里的注释保持原样（真会出现在索引顶部的注释只有这一种用法）。
+ */
+import { createHash } from "node:crypto";
+
+export const INDEX_LINE_LIMIT = 200;
+export const INDEX_CHARACTER_LIMIT = 25_000;
+
+const LEADING_FRONTMATTER_PATTERN = /^---\s*\n[\s\S]*?---\s*\n?/u;
+
+export interface FormattedMemoryIndex {
+  /** 注入用的正文；索引为空时为 ""。 */
+  text: string;
+  truncated: boolean;
+  lineCount: number;
+  characterCount: number;
+}
+
+export function formatMemoryIndexForInjection(raw: string): FormattedMemoryIndex {
+  const normalized = raw.replace(/^\uFEFF/u, "").replace(/\r\n/gu, "\n");
+  const withoutFrontmatter = normalized.replace(LEADING_FRONTMATTER_PATTERN, "");
+  const decorated = stripTopLevelHtmlComments(withoutFrontmatter);
+  return truncateMemoryIndex(decorated);
+}
+
+/** 只删代码围栏之外、行首就是 `<!--` 的顶层注释块（列表项/段落里的注释保留）。 */
+export function stripTopLevelHtmlComments(content: string): string {
+  if (!content.includes("<!--")) return content;
+  const lines = content.split("\n");
+  const out: string[] = [];
+  let fence: string | undefined;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    const trimmedStart = line.trimStart();
+    const fenceMatch = /^(`{3,}|~{3,})/u.exec(trimmedStart);
+    if (fenceMatch) {
+      if (fence === undefined) fence = fenceMatch[1]![0];
+      else if (trimmedStart.startsWith(fence.repeat(3))) fence = undefined;
+      out.push(line);
+      continue;
+    }
+    if (fence === undefined && trimmedStart.startsWith("<!--")) {
+      let end = index;
+      let closed = trimmedStart.includes("-->");
+      while (!closed && end + 1 < lines.length) {
+        end += 1;
+        if (lines[end]!.includes("-->")) closed = true;
+      }
+      if (closed) {
+        const closeIndex = lines[end]!.indexOf("-->");
+        const rest = lines[end]!.slice(closeIndex + 3);
+        index = end;
+        if (rest.trim().length > 0) out.push(rest);
+        continue;
+      }
+    }
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+export function truncateMemoryIndex(content: string): FormattedMemoryIndex {
+  const trimmed = content.trim();
+  if (trimmed.length === 0) {
+    return { text: "", truncated: false, lineCount: 0, characterCount: 0 };
+  }
+  const lines = trimmed.split("\n");
+  const lineCount = lines.length;
+  const characterCount = trimmed.length;
+  const lineTruncated = lineCount > INDEX_LINE_LIMIT;
+  const characterTruncated = characterCount > INDEX_CHARACTER_LIMIT;
+  if (!lineTruncated && !characterTruncated) {
+    return { text: trimmed, truncated: false, lineCount, characterCount };
+  }
+
+  let truncated = lineTruncated ? lines.slice(0, INDEX_LINE_LIMIT).join("\n") : trimmed;
+  if (truncated.length > INDEX_CHARACTER_LIMIT) {
+    const lastNewline = truncated.lastIndexOf("\n", INDEX_CHARACTER_LIMIT);
+    truncated = truncated.slice(0, lastNewline > 0 ? lastNewline : INDEX_CHARACTER_LIMIT);
+  }
+  const warning =
+    `> WARNING: the MEMORY.md index is too long (${lineCount} lines / ${characterCount} characters; ` +
+    `the injection limit is ${INDEX_LINE_LIMIT} lines / ${INDEX_CHARACTER_LIMIT} characters), so only the truncated part above was injected. ` +
+    `Shorten the index lines and move details into the fact files.`;
+  return {
+    text: `${truncated}\n\n${warning}`,
+    truncated: true,
+    lineCount,
+    characterCount,
+  };
+}
+
+/** 注入状态用的内容 hash（对注入正文取，保证"内容没变就不重注"）。 */
+export function memoryIndexHash(text: string): string {
+  return createHash("sha256").update(text).digest("hex");
+}