@qltk/pi-mnemo 0.1.0

package/src/dream-safety.ts

@@ -0,0 +1,181 @@
+// dream-safety.ts — post-dream validation + snapshot/rollback safety net.
+// 0.5.8: validation 语义修正（空 project scope = 合法，0.5.5 兜底 slug 常态化）
+// + .dream-backup 文件级快照回滚（替代从未实现的 git 快照方案——
+// 旧失败日志文案谎称 git 工具不可用，实际代码从无 git 调用，已删）。
+
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  mkdirSync,
+  copyFileSync,
+  unlinkSync,
+  rmSync,
+  rmdirSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+
+/** 快照目录名（memoryRoot 下）。 */
+export const BACKUP_DIRNAME = ".dream-backup";
+
+/** 不进快照/不回滚的文件（dream_log 是审计 trail，FAILED 时保留失败现场）。 */
+const EXCLUDE_FILES = new Set(["dream_log.md"]);
+
+export interface ValidationResult {
+  ok: boolean;
+  /** 失败时的真实原因（写 log + dream_log）。 */
+  reason?: string;
+}
+
+/**
+ * Validation 语义（0.5.8）：
+ * - global MEMORY.md 必须存在且索引非空（global 是主 scope）
+ * - project MEMORY.md 不存在 = 空 project scope，合法状态（不判失败）
+ * - project MEMORY.md 存在则索引不得为空
+ */
+export function validateArtifacts(
+  globalDirPath: string,
+  projectDirPath: string,
+): ValidationResult {
+  const idxLines = (f: string): number => {
+    try {
+      return readFileSync(f, "utf-8")
+        .split("\n")
+        .filter((l) => l.trim() && !l.startsWith("#") && !l.startsWith("<!--")).length;
+    } catch {
+      return -1;
+    }
+  };
+  const gMem = join(globalDirPath, "MEMORY.md");
+  if (!existsSync(gMem)) return { ok: false, reason: "global MEMORY.md missing" };
+  if (idxLines(gMem) <= 0) {
+    return { ok: false, reason: "global MEMORY.md exists but index has no topic lines" };
+  }
+  const pMem = join(projectDirPath, "MEMORY.md");
+  if (existsSync(pMem) && idxLines(pMem) <= 0) {
+    return { ok: false, reason: `project MEMORY.md (${projectDirPath}) exists but index has no topic lines` };
+  }
+  return { ok: true };
+}
+
+/** 收集 memoryRoot 下所有可快照 .md 的相对路径（排除 .dream-backup、dream_log.md）。 */
+function listSnapshottable(memoryRoot: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string, prefix: string) => {
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const n of names) {
+      if (n === BACKUP_DIRNAME) continue;
+      const full = join(dir, n);
+      let st;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        walk(full, prefix ? `${prefix}/${n}` : n);
+        continue;
+      }
+      if (!n.endsWith(".md") || EXCLUDE_FILES.has(n)) continue;
+      out.push(prefix ? `${prefix}/${n}` : n);
+    }
+  };
+  walk(memoryRoot, "");
+  return out;
+}
+
+/**
+ * dream 前快照全部 memory .md（global + 所有 projects）。
+ * 先清残留旧快照（上个 dream crash 未清理的）。
+ * 返回快照文件数。
+ */
+export function snapshotMemory(memoryRoot: string, backupDir: string): number {
+  rmSync(backupDir, { recursive: true, force: true });
+  const files = listSnapshottable(memoryRoot);
+  mkdirSync(backupDir, { recursive: true });
+  for (const rel of files) {
+    const dest = join(backupDir, rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(join(memoryRoot, rel), dest);
+  }
+  return files.length;
+}
+
+/**
+ * validation FAILED 时回滚：删除当前全部可快照 .md（含 dream 新建的），
+ * 从快照拷回，清理空 project 目录（防假 slug 进 dream backlog）。
+ * dream_log.md 不动（保留失败现场审计）。
+ * 返回 false = 无快照可回滚。
+ */
+export function restoreMemory(memoryRoot: string, backupDir: string): boolean {
+  if (!existsSync(backupDir)) return false;
+  // 1. 删现有（同规则收集，dream 新建的 .md 也会被列出删除）
+  for (const rel of listSnapshottable(memoryRoot)) {
+    try {
+      unlinkSync(join(memoryRoot, rel));
+    } catch {
+      // best-effort
+    }
+  }
+  // 2. 快照拷回
+  let restored = 0;
+  const copyBack = (src: string, dest: string) => {
+    let names: string[];
+    try {
+      names = readdirSync(src);
+    } catch {
+      return;
+    }
+    for (const n of names) {
+      const s = join(src, n);
+      const d = join(dest, n);
+      let st;
+      try {
+        st = statSync(s);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        mkdirSync(d, { recursive: true });
+        copyBack(s, d);
+      } else {
+        mkdirSync(dirname(d), { recursive: true });
+        copyFileSync(s, d);
+        restored++;
+      }
+    }
+  };
+  try {
+    copyBack(backupDir, memoryRoot);
+  } catch {
+    return false;
+  }
+  // 3. 清空 project 目录
+  try {
+    const projRoot = join(memoryRoot, "projects");
+    if (existsSync(projRoot)) {
+      for (const n of readdirSync(projRoot)) {
+        const p = join(projRoot, n);
+        try {
+          if (statSync(p).isDirectory() && readdirSync(p).length === 0) rmdirSync(p);
+        } catch {
+          // best-effort
+        }
+      }
+    }
+  } catch {
+    // best-effort
+  }
+  return true;
+}
+
+/** validation OK 后丢弃快照。 */
+export function discardBackup(backupDir: string): void {
+  rmSync(backupDir, { recursive: true, force: true });
+}

package/src/extract-success.ts

@@ -0,0 +1,28 @@
+// extract-success.ts — judge whether a fork session's messages indicate extract success.
+// 0.5.4: extract onComplete 用此判据决定是否推进 cursor（成功推进，失败保留重试）。
+//
+// 成功 = 最后一条 assistant 有有效 text（含"判断无可记"的正常返回）且无 error part。
+// 失败 = 无 assistant 回复（配额耗尽 session 无输出），或 assistant 含 error part（模型错误）。
+
+/**
+ * Judge extract success from fork session messages.
+ * Success = last assistant message has non-empty text and no error part.
+ * Failure = no assistant message, or last assistant has error part.
+ * Pure function, no side effects.
+ */
+export function isExtractSuccessful(msgs: any[]): boolean {
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const role = msgs[i]?.info?.role || msgs[i]?.role;
+    if (role === "assistant") {
+      const parts = msgs[i]?.info?.parts || msgs[i]?.parts || [];
+      const hasText = parts.some(
+        (p: any) => p?.type === "text" && typeof p.text === "string" && p.text.trim().length > 0,
+      );
+      const hasError = parts.some(
+        (p: any) => p?.type === "error" || typeof p?.error !== "undefined",
+      );
+      return hasText && !hasError;
+    }
+  }
+  return false;
+}

package/src/frontmatter.ts

@@ -0,0 +1,74 @@
+// frontmatter.ts — parse/bump frontmatter in topic files.
+// Extracted from io.js for testability. Uses TopicFrontmatter type.
+
+import { readFileSync } from "node:fs";
+import { atomicWrite } from "./atomic-writer.js";
+import type { TopicFrontmatter } from "./types.js";
+
+/** Regex to match YAML frontmatter block at start of file. */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+/**
+ * Parse YAML frontmatter from a topic file's raw content.
+ * Returns the frontmatter object + the body (content after frontmatter).
+ */
+export function parseFrontmatter(content: string): { frontmatter: TopicFrontmatter; body: string } | null {
+  const m = content.match(FRONTMATTER_RE);
+  if (!m) return null;
+  const fmText = m[1];
+  const frontmatter: TopicFrontmatter = { name: "", type: "project" };
+
+  // Simple line-based YAML parser (avoids js-yaml dependency)
+  for (const line of fmText.split("\n")) {
+    const kv = line.match(/^(\w[\w_]*):\s*(.*)$/);
+    if (!kv) continue;
+    const [, key, val] = kv;
+    if (key === "name") frontmatter.name = val;
+    else if (key === "description") frontmatter.description = val;
+    else if (key === "type") frontmatter.type = val as TopicFrontmatter["type"];
+    else if (key === "deprecated_by") frontmatter.deprecated_by = val;
+    else if (key === "usage_count") frontmatter.usage_count = parseInt(val, 10);
+    else if (key === "last_used") frontmatter.last_used = parseInt(val, 10);
+    else (frontmatter as any)[key] = val;
+  }
+
+  return { frontmatter, body: content.slice(m[0].length) };
+}
+
+/**
+ * Bump usage_count + last_used in a topic file's frontmatter.
+ * 借鉴 codex citation/usage 闭环：被引用的 topic bump usage_count + last_used。
+ * Returns true if bumped, false if no frontmatter or read error.
+ */
+export function bumpUsage(filePath: string): boolean {
+  let content: string;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch {
+    return false;
+  }
+
+  const m = content.match(FRONTMATTER_RE);
+  if (!m) return false;
+
+  let fm = m[1];
+  const now = Date.now();
+
+  const countMatch = fm.match(/^usage_count:\s*(\d+)/m);
+  const newCount = countMatch ? parseInt(countMatch[1], 10) + 1 : 1;
+
+  fm = countMatch
+    ? fm.replace(/^usage_count:\s*\d+/m, `usage_count: ${newCount}`)
+    : `${fm.trimEnd()}\nusage_count: ${newCount}`;
+
+  fm = fm.match(/^last_used:/m)
+    ? fm.replace(/^last_used:.*$/m, `last_used: ${now}`)
+    : `${fm.trimEnd()}\nlast_used: ${now}`;
+
+  try {
+    atomicWrite(filePath, `---\n${fm}\n---\n` + content.slice(m[0].length));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/io.ts

@@ -0,0 +1,25 @@
+// io.ts — memory file operations barrel.
+
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { CONFIG } from "./config.js";
+import { log } from "./log.js";
+
+// Scope helpers (need CONFIG)
+export const globalDir = (): string => CONFIG.memoryRoot;
+export const projectDir = (slug: string): string => join(CONFIG.memoryRoot, "projects", slug);
+
+// Re-exports from sibling modules
+export { readIndex, readIndexWithAge, listScopeDirs, listProjectSlugs } from "./memory-index.js";
+export { atomicWrite } from "./atomic-writer.js";
+export { parseFrontmatter, bumpUsage } from "./frontmatter.js";
+export { sanitizeText, redactSecrets, stripPrivate, sanitizeForInjection } from "./sanitizer.js";
+
+export function readPrompt(name: string): string | null {
+  try {
+    return readFileSync(join(CONFIG.promptsDir, name), "utf-8");
+  } catch (e: any) {
+    log("missing prompt", name, "—", e.message);
+    return null;
+  }
+}

package/src/log.ts

@@ -0,0 +1,21 @@
+// log.ts — append to ~/.pi/agent/mnemo/.plugin.log + stderr.
+
+import { appendFileSync, statSync, renameSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { CONFIG } from "./config.js";
+
+const LOG_FILE = () => join(CONFIG.memoryRoot, ".plugin.log");
+
+export function log(...args: unknown[]): void {
+  const line = `[${new Date().toISOString()}] ${args.map(String).join(" ")}\n`;
+  try {
+    mkdirSync(dirname(LOG_FILE()), { recursive: true });
+    try {
+      if (statSync(LOG_FILE()).size > CONFIG.logMaxBytes) {
+        renameSync(LOG_FILE(), LOG_FILE() + ".1");
+      }
+    } catch { /* not created yet */ }
+    appendFileSync(LOG_FILE(), line);
+  } catch { /* disk issues must never break the agent */ }
+  console.error("[pi-mnemo]", ...args);
+}

package/src/memory-index.ts

@@ -0,0 +1,114 @@
+// memory-index.ts — read MEMORY.md index files (with staleness annotation).
+// Extracted from io.js for testability.
+
+import { readFileSync, existsSync, statSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const MAX_LINES = 200;
+const MAX_BYTES = 25000;
+
+// Truncate MEMORY.md to line/byte caps so a bloated index can't blow up the
+// system prompt. Line-truncates first (natural boundary), then byte-truncates
+// at the last newline so we don't cut mid-line.
+function truncate(raw: string): string {
+  const trimmed = (raw || "").trim();
+  if (!trimmed) return "";
+  const lines = trimmed.split("\n");
+  const wasLineTrunc = lines.length > MAX_LINES;
+  const wasByteTrunc = trimmed.length > MAX_BYTES;
+  if (!wasLineTrunc && !wasByteTrunc) return trimmed;
+  let out = wasLineTrunc ? lines.slice(0, MAX_LINES).join("\n") : trimmed;
+  if (out.length > MAX_BYTES) {
+    const cutAt = out.lastIndexOf("\n", MAX_BYTES);
+    out = out.slice(0, cutAt > 0 ? cutAt : MAX_BYTES);
+  }
+  const why =
+    (wasLineTrunc ? `${MAX_LINES} lines` : "") +
+    (wasLineTrunc && wasByteTrunc ? " and " : "") +
+    (wasByteTrunc ? `${MAX_BYTES} bytes` : "");
+  return (
+    out +
+    `\n\n> WARNING: MEMORY.md exceeded ${why}. Only part loaded — keep entries to one line under ~200 chars; move detail into topic files.`
+  );
+}
+
+function ageDays(mtimeMs: number): number {
+  return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86_400_000));
+}
+
+/** Try alternate names agents sometimes write (MEMORY.md, INDEX.md, etc.) */
+const INDEX_NAMES = ["MEMORY.md", "INDEX.md", "memory.md", "index.md"];
+
+// Read a scope's MEMORY.md index (tolerates alternate names).
+export function readIndex(dir: string): string {
+  for (const name of INDEX_NAMES) {
+    try {
+      const f = join(dir, name);
+      if (existsSync(f)) return truncate(readFileSync(f, "utf-8"));
+    } catch {
+      // continue
+    }
+  }
+  return "";
+}
+
+// Read index + annotate each topic line with staleness based on the topic
+// file's mtime. Memories >1 day old get "[N days old — verify against current
+// code]" so the agent doesn't assert stale file:line / commands as fact.
+export function readIndexWithAge(dir: string): string {
+  const raw = readIndex(dir);
+  if (!raw.trim()) return "";
+  return raw
+    .split("\n")
+    .map((line: string) => {
+      const m = line.match(/\]\(([^)]+)\)/);
+      if (!m) return line;
+      try {
+        const fpath = join(dir, m[1]);
+        // 过滤 deprecated_by（软删除——dream 合并标记的，不注入）
+        const c = readFileSync(fpath, "utf-8");
+        const fm = c.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (fm && /^deprecated_by:/m.test(fm[1])) return null;
+        const d = ageDays(statSync(fpath).mtimeMs);
+        if (d <= 1) return line;
+        return `${line}  [${d} days old — verify against current code]`;
+      } catch {
+        return line;
+      }
+    })
+    .filter((line: string | null): line is string => line !== null)
+    .join("\n");
+}
+
+/**
+ * List all scope directories (global + project).
+ * Returns { globalDir, projectDir } for a given slug.
+ */
+export function listScopeDirs(
+  memoryRoot: string,
+  slug: string,
+): { globalDir: string; projectDir: string } {
+  return {
+    globalDir: memoryRoot,
+    projectDir: join(memoryRoot, "projects", slug),
+  };
+}
+
+/**
+ * List all project slug directories under memoryRoot/projects/.
+ * Used by dream backlog to find overdue slugs.
+ */
+export function listProjectSlugs(memoryRoot: string): string[] {
+  const projDir = join(memoryRoot, "projects");
+  try {
+    return readdirSync(projDir).filter((n) => {
+      try {
+        return statSync(join(projDir, n)).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return [];
+  }
+}