@agfpd/iapeer-memory-core 0.1.1

package/src/frontmatter-fill.ts

@@ -0,0 +1,529 @@
+/**
+ * Fill a vault note's frontmatter according to its zone
+ * (inbox / permanent / memory).
+ *
+ * TS port of the reference `scripts/mergemind-frontmatter-fill.py`
+ * (behavioural parity against `tests/python/test_frontmatter_fill.py`,
+ * 73 fixtures) with the deliberate ADR deviations:
+ *
+ * - **curator-set instead of hard-coded `index`** (ADR-006): `needs_review`
+ *   is NOT stamped when the writing agent belongs to the configured curator
+ *   set (`index`, `copywriter`, `dreamweaver` by default) — curators'
+ *   edits are sanctioned curation, not author edits awaiting review.
+ * - **taxonomy-driven zone routing** (ADR-002/011): folder names, the
+ *   agent-memory type token and emitted status tokens come from the locale
+ *   preset, not constants — the same logic runs the RU vault and the EN base.
+ * - **identity = peer personality** (нюанс 10): `resolveAgentName` prefers
+ *   `PEER_PERSONALITY`, falling back to `IAPEER_MEMORY_AGENT_NAME`.
+ *
+ * Zone behaviour (parity with the reference):
+ * - inbox:     idempotent fill of the 4-field draft frontmatter +
+ *              needs_review (unless curator).
+ * - permanent: upsert of service fields (last_edited_by, updated,
+ *              needs_review).
+ * - memory:    PERMANENT service-field semantics + idempotent fill of the
+ *              constants. `author` is parsed from the subfolder name, NOT
+ *              from the caller identity — load-bearing for DreamWeaver
+ *              writing into a foreign subfolder on an Index task.
+ *
+ * The YAML-safe normalisation of `description` is load-bearing: typographic
+ * guillemets `«…»` are a display convention, not YAML quotes; any `: ` inside
+ * such a plain scalar breaks every real YAML parser downstream (incident
+ * scan 2026-06-01: 49/538 notes unparseable on exactly this field; `sed`
+ * editing of frontmatter is banned since incident 2026-05-20).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import type { TaxonomyPreset } from "./taxonomy.js";
+import { DEFAULT_CURATOR_SET } from "./taxonomy.js";
+
+const FRONTMATTER_RE = /^---[^\S\n]*\n([\s\S]*?\n)---[^\S\n]*(?:\n|$)/;
+
+export const VALID_ZONES = ["inbox", "permanent", "memory"] as const;
+export type Zone = (typeof VALID_ZONES)[number];
+
+/**
+ * Array fields for which an empty value is meaningless and gets sanitised.
+ * Source of emptiness: the Index may have edited `coauthors:` without a
+ * following `  - <name>` item (bug phase 2026-05-20), or a draft arrived
+ * with a truncated value. The hook removes such keys idempotently.
+ */
+export const EMPTY_ARRAY_KEYS = ["tags", "coauthors"] as const;
+
+/** Fields rewritten into valid YAML by `normalizeFields`. */
+export const NORMALIZE_KEYS = ["description"] as const;
+
+export type FillContext = {
+  taxonomy: TaxonomyPreset;
+  /** ADR-006 curator set; defaults to DEFAULT_CURATOR_SET. */
+  curatorSet?: readonly string[];
+};
+
+function isCurator(agent: string, ctx: FillContext): boolean {
+  return (ctx.curatorSet ?? DEFAULT_CURATOR_SET).includes(agent);
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function hasField(block: string, key: string): boolean {
+  return new RegExp(`^${escapeRe(key)}\\s*:`, "m").test(block);
+}
+
+/** Update or insert — always sets to value. */
+export function upsert(block: string, key: string, value: string): string {
+  const pattern = new RegExp(`^${escapeRe(key)}\\s*:.*$`, "m");
+  if (pattern.test(block)) {
+    return block.replace(pattern, () => `${key}: ${value}`);
+  }
+  if (block && !block.endsWith("\n")) block += "\n";
+  return `${block}${key}: ${value}\n`;
+}
+
+/** Set only if the field is absent — preserves the author's explicit override. */
+export function setIfMissing(block: string, key: string, value: string): string {
+  if (hasField(block, key)) return block;
+  if (block && !block.endsWith("\n")) block += "\n";
+  return `${block}${key}: ${value}\n`;
+}
+
+/** Returns [fmBlock, rest]. No frontmatter → ["", content]. */
+export function splitFrontmatter(content: string): [string, string] {
+  const m = FRONTMATTER_RE.exec(content);
+  if (m) {
+    return [m[1], content.slice(m[0].length)];
+  }
+  return ["", content];
+}
+
+export function basenameNoExt(filePath: string): string {
+  const base = path.basename(filePath);
+  return base.endsWith(".md") ? base.slice(0, -3) : base;
+}
+
+function relParts(filePath: string, vault: string): string[] | null {
+  const rel = path.relative(vault, filePath);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep);
+}
+
+/**
+ * Extract the owner subfolder name from a path of the form
+ * `<vault>/<agentMemoryFolder>/<owner>/...`. Returns null when the path is
+ * outside the expected structure — the caller must abort (not our zone).
+ */
+export function parseMemoryAuthor(
+  filePath: string,
+  vault: string,
+  taxonomy: TaxonomyPreset,
+): string | null {
+  const parts = relParts(filePath, vault);
+  if (!parts || parts.length < 3 || parts[0] !== taxonomy.folders.agentMemory) {
+    return null;
+  }
+  const owner = parts[1].trim();
+  return owner || null;
+}
+
+/**
+ * Zone of a file by the first path segment relative to the vault — the
+ * single source of truth for zone routing (the reference de-duplicated a
+ * bash `case` into exactly this function). Folder whitelist comes from the
+ * taxonomy preset (ADR-002): both inboxes, archive and system are NOT in
+ * the whitelist → null → caller no-ops.
+ */
+export function resolveZone(
+  filePath: string,
+  vault: string,
+  taxonomy: TaxonomyPreset,
+): Zone | null {
+  if (!vault) return null;
+  const parts = relParts(filePath, vault);
+  if (!parts || parts.length === 0) return null;
+  const head = parts[0];
+  const f = taxonomy.folders;
+  if (head === f.inbox) return "inbox";
+  if (
+    head === f.knowledge ||
+    head === f.decisions ||
+    head === f.projects ||
+    head === f.ideas ||
+    head === f.lists
+  ) {
+    return "permanent";
+  }
+  if (head === f.agentMemory) return "memory";
+  return null;
+}
+
+export function fillInbox(
+  fmBlock: string,
+  opts: { path: string; agent: string; today: string; ctx: FillContext },
+): string {
+  const { taxonomy } = opts.ctx;
+  fmBlock = setIfMissing(fmBlock, "title", basenameNoExt(opts.path));
+  fmBlock = setIfMissing(fmBlock, "status", taxonomy.statusTokens.draft);
+  fmBlock = setIfMissing(fmBlock, "created", opts.today);
+  fmBlock = setIfMissing(fmBlock, "author", opts.agent);
+  if (!isCurator(opts.agent, opts.ctx)) {
+    fmBlock = setIfMissing(fmBlock, "needs_review", "true");
+  }
+  return fmBlock;
+}
+
+export function fillPermanent(
+  fmBlock: string,
+  opts: { agent: string; nowStamp: string; ctx: FillContext },
+): string {
+  fmBlock = upsert(fmBlock, "last_edited_by", opts.agent);
+  fmBlock = upsert(fmBlock, "updated", opts.nowStamp);
+  if (!isCurator(opts.agent, opts.ctx)) {
+    fmBlock = upsert(fmBlock, "needs_review", "true");
+  }
+  return fmBlock;
+}
+
+/**
+ * Returns the updated block, or null when the path is outside the expected
+ * `<agentMemoryFolder>/<owner>/...` structure while a vault is provided
+ * (caller aborts processing).
+ */
+export function fillMemory(
+  fmBlock: string,
+  opts: {
+    path: string;
+    agent: string;
+    vault: string;
+    today: string;
+    nowStamp: string;
+    ctx: FillContext;
+  },
+): string | null {
+  const { taxonomy } = opts.ctx;
+  fmBlock = upsert(fmBlock, "last_edited_by", opts.agent);
+  fmBlock = upsert(fmBlock, "updated", opts.nowStamp);
+  if (!isCurator(opts.agent, opts.ctx)) {
+    fmBlock = upsert(fmBlock, "needs_review", "true");
+  }
+
+  let authorForConstants: string;
+  if (opts.vault) {
+    const parsed = parseMemoryAuthor(opts.path, opts.vault, taxonomy);
+    if (parsed === null) return null;
+    authorForConstants = parsed;
+  } else {
+    authorForConstants = opts.agent;
+  }
+
+  fmBlock = setIfMissing(fmBlock, "title", basenameNoExt(opts.path));
+  fmBlock = setIfMissing(fmBlock, "type", taxonomy.types.agentMemory);
+  fmBlock = setIfMissing(fmBlock, "status", taxonomy.statusTokens.current);
+  fmBlock = setIfMissing(fmBlock, "created", opts.today);
+  fmBlock = setIfMissing(fmBlock, "author", authorForConstants);
+  return fmBlock;
+}
+
+/**
+ * Remove keys whose value is an empty YAML array. Recognises three forms of
+ * emptiness, leaves everything else intact:
+ * - `key:` with no value and no following `  - item` lines (empty block form);
+ * - `key: []` — inline empty array;
+ * - `key: null` / `key: ~` — explicit null.
+ */
+export function stripEmptyArrays(
+  fmBlock: string,
+  keys: readonly string[] = EMPTY_ARRAY_KEYS,
+): string {
+  const lines = fmBlock.split("\n");
+  const out: string[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const m = /^([A-Za-z_][\w-]*)\s*:\s*(.*?)\s*$/.exec(line);
+    if (m && keys.includes(m[1])) {
+      const value = m[2];
+      if (value === "[]" || value === "null" || value === "~") {
+        i += 1;
+        continue;
+      }
+      if (value === "") {
+        const nxt = i + 1 < lines.length ? lines[i + 1] : "";
+        if (!/^\s+-\s/.test(nxt)) {
+          i += 1;
+          continue;
+        }
+      }
+    }
+    out.push(line);
+    i += 1;
+  }
+  return out.join("\n");
+}
+
+// --- YAML-safe scalar normalisation (load-bearing) --------------------------
+
+/** Leading characters that make a plain scalar invalid/ambiguous in YAML. */
+const YAML_INDICATORS = new Set([..."!&*?|>%@`\"'#,[]{}"]);
+
+/** v is a well-formed, terminated double-quoted YAML scalar. */
+export function isCleanDoubleQuoted(v: string): boolean {
+  if (v.length < 2 || v[0] !== '"') return false;
+  let i = 1;
+  const n = v.length;
+  while (i < n) {
+    if (v[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (v[i] === '"') return i === n - 1;
+    i += 1;
+  }
+  return false;
+}
+
+/** v is a well-formed, terminated single-quoted YAML scalar (escape is `''`). */
+export function isCleanSingleQuoted(v: string): boolean {
+  if (v.length < 2 || v[0] !== "'") return false;
+  let i = 1;
+  const n = v.length;
+  while (i < n) {
+    if (v[i] === "'") {
+      if (i + 1 < n && v[i + 1] === "'") {
+        i += 2;
+        continue;
+      }
+      return i === n - 1;
+    }
+    i += 1;
+  }
+  return false;
+}
+
+/**
+ * Plain scalar `v` is unsafe (would parse as something other than a string
+ * literal, or crash the parser). Empty and block scalars (`|`/`>`) never
+ * reach this — filtered earlier.
+ */
+export function yamlNeedsQuoting(v: string): boolean {
+  if (!v) return false;
+  if (YAML_INDICATORS.has(v[0]) || v[0] === ":") return true;
+  if (v[0] === "-" && (v.length === 1 || v[1] === " " || v[1] === "\t")) return true;
+  if (v.includes(": ") || v.endsWith(":")) return true;
+  if (v.includes(" #")) return true;
+  if (v.includes("\t")) return true;
+  return false;
+}
+
+/** Serialise string `s` as a valid double-quoted YAML scalar. */
+export function yamlDoubleQuote(s: string): string {
+  const out: string[] = ['"'];
+  for (const ch of s) {
+    if (ch === "\\") out.push("\\\\");
+    else if (ch === '"') out.push('\\"');
+    else if (ch === "\n") out.push("\\n");
+    else if (ch === "\t") out.push("\\t");
+    else if (ch === "\r") out.push("\\r");
+    else if (ch.codePointAt(0)! < 0x20) {
+      out.push(`\\x${ch.codePointAt(0)!.toString(16).padStart(2, "0")}`);
+    } else out.push(ch);
+  }
+  out.push('"');
+  return out.join("");
+}
+
+/**
+ * Strip convention delimiters that YAML does not recognise as quotes,
+ * keeping the logical content. `«…»` — the description convention pair.
+ * A dangling (unterminated) leading `'`/`"` is an artefact of a truncated
+ * quoted value: strip the leading one and the paired trailing one if present.
+ */
+export function stripBrokenDelims(v: string): string {
+  v = v.trim();
+  if (v.length >= 2 && v[0] === "«" && v[v.length - 1] === "»") {
+    return v.slice(1, -1).trim();
+  }
+  if (v.startsWith("'")) {
+    v = v.slice(1);
+    if (v.endsWith("'")) v = v.slice(0, -1);
+    return v.replaceAll("''", "'").trim();
+  }
+  if (v.startsWith('"')) {
+    v = v.slice(1);
+    if (v.endsWith('"')) v = v.slice(0, -1);
+    return v.trim();
+  }
+  return v;
+}
+
+/**
+ * Return the YAML-safe representation of a scalar value, or null when no
+ * edit is needed (already valid / empty / block scalar). `raw` is the text
+ * after `key:`.
+ */
+export function normalizeScalarValue(raw: string): string | null {
+  const v = raw.trim();
+  if (!v || v[0] === "|" || v[0] === ">") return null;
+  if (isCleanDoubleQuoted(v) || isCleanSingleQuoted(v)) return null;
+  if (!yamlNeedsQuoting(v)) return null;
+  return yamlDoubleQuote(stripBrokenDelims(v));
+}
+
+const NORMALIZE_LINE_RE = /^([A-Za-z_][\w-]*):[ \t]?(.*)$/;
+
+/**
+ * Rewrite the values of `keys` fields into valid YAML. Line-based: vault
+ * frontmatter is flat (one `key: value` per line); block-list fields
+ * (tags/coauthors) are not in `keys`. Idempotent.
+ */
+export function normalizeFields(
+  fmBlock: string,
+  keys: readonly string[] = NORMALIZE_KEYS,
+): string {
+  const lines = fmBlock.split("\n");
+  for (let idx = 0; idx < lines.length; idx++) {
+    const m = NORMALIZE_LINE_RE.exec(lines[idx]);
+    if (!m || !keys.includes(m[1])) continue;
+    const newVal = normalizeScalarValue(m[2]);
+    if (newVal !== null) {
+      lines[idx] = `${m[1]}: ${newVal}`;
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Assemble the new file. A body not starting with a newline gets one, so the
+ * markdown parser sees the frontmatter separately from the first paragraph.
+ */
+export function assemble(fmBlock: string, rest: string): string {
+  if (rest && !rest.startsWith("\n")) rest = "\n" + rest;
+  return "---\n" + fmBlock + "---\n" + rest;
+}
+
+/** temp file + rename — atomic write on POSIX. */
+export function atomicWrite(filePath: string, content: string): void {
+  const tmp = path.join(
+    path.dirname(filePath),
+    `.fm-${crypto.randomBytes(6).toString("hex")}.tmp`,
+  );
+  try {
+    fs.writeFileSync(tmp, content, "utf-8");
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    } catch {
+      // best effort
+    }
+    throw err;
+  }
+}
+
+function pad(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+function localDateIso(d: Date): string {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+/**
+ * `YYYY-MM-DD HH:MM:SS` — second precision is deliberate: the human-edit
+ * detector tells an agent edit (hook just ran) from an external-editor edit
+ * by the freshness of `updated` relative to a window; minute truncation ate
+ * up to 59s of that window and caused mis-attribution loops. Parsers accept
+ * the legacy `YYYY-MM-DD HH:MM` too.
+ */
+function localStamp(d: Date): string {
+  return `${localDateIso(d)} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+export type ProcessOptions = {
+  zone: Zone | "auto";
+  agent: string;
+  vault?: string;
+  /** Injectable for tests; defaults to new Date(). */
+  now?: Date;
+  taxonomy: TaxonomyPreset;
+  curatorSet?: readonly string[];
+};
+
+/**
+ * Main entry. Returns true when the file was changed, false on no-op.
+ * zone === "auto" resolves the zone from the path (whitelist of canonical
+ * folders); a path outside the whitelist is a no-op.
+ */
+export function processFile(filePath: string, opts: ProcessOptions): boolean {
+  const ctx: FillContext = { taxonomy: opts.taxonomy, curatorSet: opts.curatorSet };
+  const vault = opts.vault ?? "";
+
+  let zone: Zone;
+  if (opts.zone === "auto") {
+    const resolved = resolveZone(filePath, vault, opts.taxonomy);
+    if (resolved === null) return false;
+    zone = resolved;
+  } else {
+    zone = opts.zone;
+  }
+  if (!VALID_ZONES.includes(zone)) return false;
+  if (!opts.agent) return false;
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return false;
+  }
+  if (!stat.isFile()) return false;
+
+  const now = opts.now ?? new Date();
+  const today = localDateIso(now);
+  const nowStamp = localStamp(now);
+
+  const content = fs.readFileSync(filePath, "utf-8");
+  const [fmBlock, rest] = splitFrontmatter(content);
+
+  let newFm: string | null;
+  if (zone === "inbox") {
+    newFm = fillInbox(fmBlock, { path: filePath, agent: opts.agent, today, ctx });
+  } else if (zone === "permanent") {
+    newFm = fillPermanent(fmBlock, { agent: opts.agent, nowStamp, ctx });
+  } else {
+    newFm = fillMemory(fmBlock, {
+      path: filePath,
+      agent: opts.agent,
+      vault,
+      today,
+      nowStamp,
+      ctx,
+    });
+    if (newFm === null) return false;
+  }
+
+  newFm = stripEmptyArrays(newFm);
+  newFm = normalizeFields(newFm);
+  const newContent = assemble(newFm, rest);
+  if (newContent === content) return false;
+  atomicWrite(filePath, newContent);
+  return true;
+}
+
+/**
+ * Resolve the writing identity (нюанс 10): explicit value first, then the
+ * stable iapeer identity `PEER_PERSONALITY`, then the namespace fallback
+ * `IAPEER_MEMORY_AGENT_NAME` (non-peer sessions). Null when nothing is set —
+ * the caller must no-op, never guess from cwd.
+ */
+export function resolveAgentName(
+  explicit?: string | null,
+  env: Record<string, string | undefined> = process.env,
+): string | null {
+  const candidates = [explicit, env.PEER_PERSONALITY, env.IAPEER_MEMORY_AGENT_NAME];
+  for (const c of candidates) {
+    const v = (c ?? "").trim();
+    if (v) return v;
+  }
+  return null;
+}