@lh8ppl/claude-memory-kit 0.3.5 → 0.4.1

package/src/kiro-ide-hooks.mjs

@@ -0,0 +1,219 @@
+// kiro-ide-hooks.mjs — write Kiro IDE hook files (Task 50.K + 50.N.3 v1 migration).
+//
+// TWO formats, DUAL-EMITTED for back-compat (D-203):
+//
+//   LEGACY (Kiro 0.x) — individual `.kiro/hooks/<name>.kiro.hook` files:
+//     { "version": "1.0.0", "enabled", "name", "description",
+//       "when": { "type": "agentStop" },
+//       "then": { "type": "runCommand", "command", "timeout" } }
+//   Verified from a real GUI-created 0.x hook (P-WJRUQVSW).
+//
+//   v1 (Kiro IDE 1.0+) — clean per-hook `.kiro/hooks/<name>.json` files that
+//   REPLACE the .kiro.hook format (which 1.0 no longer loads — D-203). Schema
+//   GROUND-TRUTH-VERIFIED against Kiro IDE 1.0's OWN migration output (D-203d —
+//   it migrated our `cmk-capture.kiro.hook` → `cmk-capture.json`):
+//     { "version": "v1", "hooks": [ { "name", "description", "trigger",
+//       "matcher"?, "action": { "type": "command", "command" }, "timeout",
+//       "enabled" } ] }   — PascalCase triggers; `action.type:'command'` is the
+//   deterministic-shell action (no LLM). We write `cmk-capture.json`/
+//   `cmk-inject.json`/`cmk-guard.json`/`cmk-observe.json` — Kiro's exact filename
+//   convention, one hook per file (full isolation).
+//
+// v1 lets the IDE do the FULL Claude-Code hook set (one clean .json file PER
+// hook): inject (UserPromptSubmit) + capture (Stop) + delete-guard (PreToolUse —
+// CAN BLOCK on non-zero exit) + observe-edit (PostToolUse).
+//
+// We emit BOTH so a 0.x user keeps the legacy hooks and a 1.0 user gets v1 (a
+// 1.0 IDE runs the .json + shows the .kiro.hook as inert "legacy"; a 0.x IDE
+// runs the .kiro.hook + ignores the .json — no double-fire, verified D-203d).
+//
+// ⚠️ v1 behaviors LIVE-PROBED at the cut-gate (D-203 — `Stop` + the schema are
+// CONFIRMED by Kiro 1.0's own migration D-203d; the rest flagged, NOT asserted):
+// (1) auto-load of an installer-written json; (2) what a PreToolUse command
+// receives (the path to inspect); (3) exit-code 1-vs-2 to
+// block; (4) the matcher tool-name tokens; (5) the real session-end trigger
+// name (v1's type list has SessionStart but no obvious Stop — we use `Stop`,
+// the dispatcher's capture key, pending the probe).
+//
+// Public surface:
+//   installKiroIdeHooks({ projectRoot, command? }) → { action, changed, hooks }
+//   uninstallKiroIdeHooks({ projectRoot }) → { action, changed, hooks }
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { kiroHookCommand, kiroGuardCommand } from './kiro-hook-command.mjs';
+
+const CMK = 'cmk';
+const MANAGED = 'Managed by `cmk install` — do not hand-edit.';
+
+// The platform-correct `cmk hook <event>` command (cmd.exe /c on Windows where
+// Kiro routes hooks through WSL) is shared from kiro-hook-command.mjs.
+const hookCommand = kiroHookCommand;
+
+// One .kiro.hook spec. We intentionally do NOT put a `then` key on any JS object
+// here — Kiro's schema needs a top-level `then` (its "action" leg), but a JS
+// object with a `then` property is a "thenable" footgun (a static analyzer flags
+// it, and an accidental thenable can hijack a Promise chain). So we model the
+// action under a neutral `action` key and rename it to `then` ONLY at
+// serialization (serializeHook), where it's pure JSON data, never a live object.
+function hookSpecs(cmd) {
+  return [
+    {
+      file: 'cmk-capture.kiro.hook',
+      version: '1.0.0',
+      enabled: true,
+      name: 'claude-memory-kit: capture',
+      description: 'Capture durable memory at the end of each turn (claude-memory-kit). Managed by `cmk install` — do not hand-edit.',
+      when: { type: 'agentStop' },
+      action: { type: 'runCommand', command: hookCommand('stop', cmd), timeout: 60 },
+    },
+    {
+      file: 'cmk-inject.kiro.hook',
+      version: '1.0.0',
+      enabled: true,
+      name: 'claude-memory-kit: recall',
+      description: 'Inject recalled memory on each prompt (claude-memory-kit). Managed by `cmk install` — do not hand-edit.',
+      when: { type: 'promptSubmit' },
+      action: { type: 'runCommand', command: hookCommand('promptSubmit', cmd), timeout: 30 },
+    },
+  ];
+}
+
+// Serialize a spec to the Kiro .kiro.hook JSON, mapping our internal `action`
+// key to Kiro's required `then` field. We build the object with a placeholder
+// key, then rename it in the JSON STRING — so no JS object literal ever carries
+// a `then` property (the thenable footgun the static analyzer guards against).
+const THEN_PLACEHOLDER = '__kiro_then__';
+function serializeHook(spec) {
+  const { file, action, ...rest } = spec;
+  const obj = { ...rest, [THEN_PLACEHOLDER]: action };
+  return `${JSON.stringify(obj, null, 2).replace(`"${THEN_PLACEHOLDER}"`, '"then"')}\n`;
+}
+
+// The v1 hooks — ONE clean `<name>.json` file PER hook (Kiro IDE 1.0's own
+// convention — D-203d). One hook per file → every hook independently isolated (a
+// bad trigger can't dark the others). The full Claude-Code parity set:
+//   cmk-capture.json → Stop             → capture (turn-end)
+//   cmk-inject.json  → UserPromptSubmit → inject (recall)
+//   cmk-guard.json   → PreToolUse       → delete-guard (CAN BLOCK on non-zero exit)
+//   cmk-observe.json → PostToolUse      → observe-edit (record large edits)
+// Schema GROUND-TRUTH-verified against Kiro IDE 1.0's own migration output (D-203d):
+// {version:'v1', hooks:[{name, description, trigger, matcher?, action:{type:
+// 'command', command}, timeout, enabled}]}.
+//
+// SINGLE SOURCE: filename → hook-spec builder. V1_FILES is DERIVED from these keys
+// (no array/switch to keep in sync). `Stop` (capture) is CONFIRMED by Kiro's
+// migration; the other three triggers + the `fs_write` matcher are live-probed
+// (cut-gate KHv1-*).
+function v1HookFile(hook) {
+  return { version: 'v1', hooks: [hook] };
+}
+const V1_HOOK_BUILDERS = Object.freeze({
+  'cmk-capture.json': (cmd) =>
+    v1HookFile({
+      name: 'claude-memory-kit: capture',
+      description: `Capture durable memory at the end of each turn (claude-memory-kit). ${MANAGED}`,
+      trigger: 'Stop', // CONFIRMED by Kiro IDE 1.0's own migration (D-203d)
+      action: { type: 'command', command: hookCommand('stop', cmd) },
+      timeout: 60,
+      enabled: true,
+    }),
+  'cmk-inject.json': (cmd) =>
+    v1HookFile({
+      name: 'claude-memory-kit: recall',
+      description: `Inject recalled memory on each prompt (claude-memory-kit). ${MANAGED}`,
+      trigger: 'UserPromptSubmit',
+      action: { type: 'command', command: hookCommand('userPromptSubmit', cmd) },
+      timeout: 30,
+      enabled: true,
+    }),
+  'cmk-guard.json': () =>
+    v1HookFile({
+      name: 'claude-memory-kit: delete-guard',
+      description: `Block a destructive command aimed at a memory path (claude-memory-kit). ${MANAGED}`,
+      trigger: 'PreToolUse', // v1 PreToolUse can BLOCK (non-zero exit) — supersedes Task 165(b)
+      // `matcher` for PreToolUse is a TOOL-NAME glob (D-203 item 4 — exact tokens
+      // live-unverified). `'*'` is conservative; the guard itself filters to memory
+      // deletes, so an over-broad matcher costs nothing (allows all non-deletes).
+      matcher: '*',
+      action: { type: 'command', command: kiroGuardCommand() },
+      timeout: 5,
+      enabled: true,
+    }),
+  'cmk-observe.json': (cmd) =>
+    v1HookFile({
+      name: 'claude-memory-kit: observe-edit',
+      description: `Record large file edits (claude-memory-kit). ${MANAGED}`,
+      // PostToolUse (NOT PostFileSave) — observe-edit needs a TOOL-USE payload
+      // ({tool_name:'fs_write', …}) that observeEdit reads; a file-SAVE event
+      // carries no tool_name → silent noop (skill-review I1). Sibling of the
+      // kiro-cli postToolUse leg (50.N.2), same payload shape.
+      trigger: 'PostToolUse',
+      matcher: 'fs_write', // tool-name glob (like PreToolUse), scoped to file-writes
+      action: { type: 'command', command: hookCommand('postToolUse', cmd) },
+      timeout: 30,
+      enabled: true,
+    }),
+});
+
+// V1_FILES is DERIVED from the builder keys — single source of truth, no array
+// to keep in sync (an unmapped filename is structurally impossible).
+const V1_FILES = Object.freeze(Object.keys(V1_HOOK_BUILDERS));
+
+function serializeV1(file, cmd) {
+  return `${JSON.stringify(V1_HOOK_BUILDERS[file](cmd), null, 2)}\n`;
+}
+
+export function installKiroIdeHooks({ projectRoot, command = CMK } = {}) {
+  if (!projectRoot) throw new Error('installKiroIdeHooks: projectRoot is required');
+  const hooksDir = join(projectRoot, '.kiro', 'hooks');
+
+  let changed = false;
+  const written = [];
+  // 1. Legacy .kiro.hook files (Kiro 0.x back-compat).
+  for (const spec of hookSpecs(command)) {
+    const path = join(hooksDir, spec.file);
+    const serialized = serializeHook(spec);
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    if (existing !== serialized) {
+      mkdirSync(hooksDir, { recursive: true });
+      writeFileSync(path, serialized, 'utf8');
+      changed = true;
+    }
+    written.push(spec.file);
+  }
+  // 2. The v1 files (Kiro IDE 1.0+ — D-203/D-203d). A 0.x IDE ignores them; a 1.0
+  //    IDE ignores the stale .kiro.hook files above (shows them "legacy", inert —
+  //    no double-fire, verified D-203d). ONE clean `<name>.json` PER hook (Kiro's
+  //    own migration convention), so every hook is isolated.
+  for (const file of V1_FILES) {
+    const path = join(hooksDir, file);
+    const serialized = serializeV1(file, command);
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    if (existing !== serialized) {
+      mkdirSync(hooksDir, { recursive: true });
+      writeFileSync(path, serialized, 'utf8');
+      changed = true;
+    }
+    written.push(file);
+  }
+  return { action: 'installed', changed, hooks: written };
+}
+
+export function uninstallKiroIdeHooks({ projectRoot, command = CMK } = {}) {
+  if (!projectRoot) throw new Error('uninstallKiroIdeHooks: projectRoot is required');
+  const hooksDir = join(projectRoot, '.kiro', 'hooks');
+  let changed = false;
+  const removed = [];
+  // legacy .kiro.hook files + all the v1 files — remove all.
+  const ourFiles = [...hookSpecs(command).map((s) => s.file), ...V1_FILES];
+  for (const file of ourFiles) {
+    const path = join(hooksDir, file);
+    if (existsSync(path)) {
+      rmSync(path, { force: true });
+      changed = true;
+      removed.push(file);
+    }
+  }
+  return { action: 'uninstalled', changed, hooks: removed };
+}

package/src/kiro-permissions.mjs

@@ -0,0 +1,175 @@
+// kiro-permissions.mjs — write Kiro IDE 1.0's authoritative trust store so the
+// kit's surfaces run prompt-free (Task 50.N.5 / D-203h/D-203i).
+//
+// On Kiro IDE 1.0, the LIVE trust is `~/.kiro/workspace-roots/<hash>/
+// permissions.yaml` (capability/match/effect), NOT `.vscode/settings.json` — Kiro
+// auto-MIGRATES the latter into the former at first open (D-203i: proven by the
+// `.trust-migration.json` sibling + MCP running prompt-free with no `.vscode`
+// trustedMcpTools). There is NO `.vscode` setting for SKILL trust, so the only
+// reliable pre-trust for the memory-write skill-load prompt is to write
+// permissions.yaml directly.
+//
+// <hash> = sha256( projectRoot, normalized: forward-slash + no-trailing-slash +
+// lowercase ).hexdigest().slice(0,16) — VERIFIED on a real install (D-203h:
+// c:/temp/kiro-ide-gate → a7ffdb64ec4c31c8).
+//
+// Format (ground-truth, read from a real grant — D-203h):
+//   rules:
+//     - { capability: shell, match: [cmd.exe /c cmk hook *, ...], effect: allow }
+//     - { capability: mcp,   match: [claude-memory-kit/mk_remember, ...], effect: allow }
+//     - { capability: skill, match: [memory-write, memory-search], effect: allow }
+//
+// Public surface:
+//   kiroWorkspaceHash(projectRoot) → string (the 16-hex workspace key)
+//   installKiroPermissions({ projectRoot, env? }) → { action, changed, path }
+//   uninstallKiroPermissions({ projectRoot, env? }) → { action, changed }
+//
+// Managed-merge: we own ONLY the rules whose capability+match are ours (matched
+// by the kit's known tokens); a user's own rules are byte-preserved on install +
+// uninstall (the over-mutation discipline).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import yaml from 'js-yaml';
+
+import { MCP_AUTO_APPROVE } from './kiro-constants.mjs';
+
+// The kit's MCP tools, namespaced as Kiro's permissions.yaml lists them
+// (server/tool). MCP_AUTO_APPROVE is the shared source of the 11 tool names
+// (also used for the IDE's mcp.json autoApprove), so the two never drift.
+const MCP_MATCH = MCP_AUTO_APPROVE.map((t) => `claude-memory-kit/${t}`);
+const SHELL_MATCH = Object.freeze(['cmd.exe /c cmk hook *', 'cmd.exe /c cmk-guard-memory*']);
+const SKILL_MATCH = Object.freeze(['memory-write', 'memory-search']);
+
+// The kit's owned MATCH ENTRIES, per capability+effect. Ownership is PER-ENTRY
+// (not per-rule): Kiro stores ONE rule per (capability, effect) with a combined
+// `match` array, so a user can co-locate their own match in the SAME rule as ours.
+// We add/remove only OUR entries and never drop a co-located user entry (the
+// over-mutation discipline — mirrors kiro-trusted-commands.mjs's per-entry filter,
+// skill-review B1).
+const OUR_MATCHES = Object.freeze({
+  shell: SHELL_MATCH,
+  mcp: MCP_MATCH,
+  skill: SKILL_MATCH,
+});
+function isOurMatch(capability, entry) {
+  const owned = OUR_MATCHES[capability];
+  return Array.isArray(owned) && owned.includes(entry);
+}
+
+// Merge our match entries into an existing rules array, PER-ENTRY + PER-(capability,
+// effect:allow) rule. Preserves the user's rules + their co-located match entries;
+// adds only the missing OUR entries; keeps rule order stable (in-place, no float).
+function withOurRules(existing) {
+  // clone so we never mutate the parsed input
+  const rules = existing.map((r) => ({ ...r, match: Array.isArray(r.match) ? [...r.match] : r.match }));
+  for (const [capability, owned] of Object.entries(OUR_MATCHES)) {
+    // find the existing allow-rule for this capability (Kiro's convention: one per cap)
+    let rule = rules.find((r) => r && r.capability === capability && r.effect === 'allow' && Array.isArray(r.match));
+    if (!rule) {
+      rule = { capability, match: [], effect: 'allow' };
+      rules.push(rule);
+    }
+    for (const m of owned) if (!rule.match.includes(m)) rule.match.push(m);
+  }
+  return rules;
+}
+
+// Remove our match entries PER-ENTRY; drop a rule only if its match becomes empty
+// AND it was an allow-rule for a capability we own (never delete a user's rule).
+function withoutOurRules(existing) {
+  const out = [];
+  let changed = false;
+  for (const r of existing) {
+    if (!r || r.capability == null || r.effect !== 'allow' || !Array.isArray(r.match) || !OUR_MATCHES[r.capability]) {
+      out.push(r); // not a rule we touch
+      continue;
+    }
+    const kept = r.match.filter((m) => !isOurMatch(r.capability, m));
+    if (kept.length !== r.match.length) changed = true;
+    if (kept.length > 0) out.push({ ...r, match: kept }); // user entries survive
+    // else: the rule was ours-only → drop it
+  }
+  return { rules: out, changed };
+}
+
+/**
+ * Kiro IDE 1.0's workspace-roots hash for a project path.
+ * sha256(forward-slash + no-trailing-slash + lowercase).slice(0,16). (D-203h)
+ */
+export function kiroWorkspaceHash(projectRoot) {
+  // resolve() a RELATIVE input to absolute (defense — Kiro keys on the absolute
+  // workspace root; a relative path would hash to a dir Kiro never reads, review
+  // M1). An ALREADY-absolute path (drive-letter `C:\…` or POSIX `/…`) is passed
+  // through verbatim — so a Windows path stays correct even when this runs on a
+  // POSIX CI (resolve() there would wrongly prepend cwd to `c:/…`). NOTE: only
+  // ordinary drive-letter paths are ground-truth-verified (D-203h); UNC/extended-
+  // length are untested.
+  const p = String(projectRoot);
+  const isAbsolute = /^[a-zA-Z]:[\\/]/.test(p) || /^[\\/]/.test(p);
+  const abs = isAbsolute ? p : resolve(p);
+  const norm = abs.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  return createHash('sha256').update(norm).digest('hex').slice(0, 16);
+}
+
+function permissionsPath(projectRoot, env) {
+  const home = env.USERPROFILE || env.HOME || homedir();
+  return join(home, '.kiro', 'workspace-roots', kiroWorkspaceHash(projectRoot), 'permissions.yaml');
+}
+
+// Parse an existing permissions.yaml → its rules array. A missing file → []. A
+// MALFORMED file → { malformed: true } so the caller REFUSES to overwrite it
+// (mirrors kiro-trusted-commands' don't-clobber-a-corrupt-file posture, review
+// M3 — this writes to the user's HOME; never destroy content we couldn't parse).
+function readRules(path) {
+  if (!existsSync(path)) return { rules: [], existed: false };
+  let parsed;
+  try {
+    parsed = yaml.load(readFileSync(path, 'utf8'));
+  } catch {
+    return { rules: [], existed: true, malformed: true };
+  }
+  // a parse that yields a non-object (e.g. a stray scalar) is also unsafe to clobber.
+  if (parsed != null && typeof parsed !== 'object') return { rules: [], existed: true, malformed: true };
+  const rules = parsed && Array.isArray(parsed.rules) ? parsed.rules : [];
+  return { rules, existed: true };
+}
+
+function serialize(rules) {
+  // js-yaml dump; flow-style for the compact match arrays Kiro uses is optional —
+  // block style is equally valid YAML and is what Kiro itself wrote.
+  return yaml.dump({ rules }, { lineWidth: -1, noRefs: true });
+}
+
+export function installKiroPermissions({ projectRoot, env = process.env } = {}) {
+  if (!projectRoot) throw new Error('installKiroPermissions: projectRoot is required');
+  const path = permissionsPath(projectRoot, env);
+  const { rules: existing, malformed } = readRules(path);
+  if (malformed) return { action: 'skipped', changed: false, path, reason: 'malformed-permissions-yaml' };
+  const merged = withOurRules(existing); // per-entry merge — preserves order + user entries
+  const serialized = serialize(merged);
+
+  const prior = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  let changed = false;
+  if (prior !== serialized) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serialized, 'utf8');
+    changed = true;
+  }
+  return { action: 'installed', changed, path };
+}
+
+export function uninstallKiroPermissions({ projectRoot, env = process.env } = {}) {
+  if (!projectRoot) throw new Error('uninstallKiroPermissions: projectRoot is required');
+  const path = permissionsPath(projectRoot, env);
+  if (!existsSync(path)) return { action: 'uninstalled', changed: false };
+  const { rules: existing } = readRules(path);
+  const { rules: kept, changed: removed } = withoutOurRules(existing); // per-entry removal
+  if (!removed) return { action: 'uninstalled', changed: false }; // none of ours present
+  // preserve the user's rules + co-located entries; write back without ours (never
+  // delete the file — it may hold the user's own + Kiro's migration data).
+  writeFileSync(path, serialize(kept), 'utf8');
+  return { action: 'uninstalled', changed: true };
+}

package/src/kiro-skills.mjs

@@ -0,0 +1,96 @@
+// kiro-skills.mjs — install the kit's memory skills into Kiro (Task 50.I, skills leg).
+//
+// Kiro's skill surface is Claude-Code-style <name>/SKILL.md with YAML frontmatter
+// (verified from real installs: .kiro/skills/<name>/SKILL.md project-tier,
+// ~/.kiro/skills/<name>/SKILL.md user-tier). The kit already ships memory-search
+// + memory-write as SKILL.md under template/.claude/skills/ — they port directly.
+// The only transform: drop the Claude-Code-specific frontmatter keys Kiro doesn't
+// honor (`context`, `allowed-tools`) while keeping `name` + `description` + the
+// instruction body. The cmk MCP tools the skills reference are wired by the MCP
+// leg, so the skill body works unchanged.
+//
+// Public surface:
+//   installKiroSkills({ projectRoot, templateDir? }) → { action, changed, skills }
+//   uninstallKiroSkills({ projectRoot }) → { action, changed, skills }
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveTemplateDir } from './install.mjs';
+
+// The kit skills that map to Kiro. (memory-search + memory-write — the two the
+// kit scaffolds for Claude Code.)
+const KIT_SKILLS = ['memory-search', 'memory-write'];
+
+// Frontmatter keys Kiro does NOT use — dropped on translation. Everything else
+// in the frontmatter (name, description) + the whole body is preserved.
+const DROP_KEYS = new Set(['context', 'allowed-tools']);
+
+export function installKiroSkills({ projectRoot, templateDir } = {}) {
+  if (!projectRoot) throw new Error('installKiroSkills: projectRoot is required');
+  const tpl = templateDir || resolveTemplateDir();
+  const skillsRoot = join(projectRoot, '.kiro', 'skills');
+
+  let changed = false;
+  const installed = [];
+  for (const name of KIT_SKILLS) {
+    const src = join(tpl, '.claude', 'skills', name, 'SKILL.md');
+    if (!existsSync(src)) continue; // skill not in this template — skip, don't fail
+    const translated = translateFrontmatter(readFileSync(src, 'utf8'));
+    const destDir = join(skillsRoot, name);
+    const dest = join(destDir, 'SKILL.md');
+
+    const existing = existsSync(dest) ? readFileSync(dest, 'utf8') : null;
+    if (existing !== translated) {
+      mkdirSync(destDir, { recursive: true });
+      writeFileSync(dest, translated, 'utf8');
+      changed = true;
+    }
+    installed.push(name);
+  }
+  return { action: 'installed', changed, skills: installed };
+}
+
+export function uninstallKiroSkills({ projectRoot } = {}) {
+  if (!projectRoot) throw new Error('uninstallKiroSkills: projectRoot is required');
+  const skillsRoot = join(projectRoot, '.kiro', 'skills');
+  let changed = false;
+  const removed = [];
+  for (const name of KIT_SKILLS) {
+    const dir = join(skillsRoot, name);
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true, force: true });
+      changed = true;
+      removed.push(name);
+    }
+  }
+  return { action: 'uninstalled', changed, skills: removed };
+}
+
+// ── internal ─────────────────────────────────────────────────────────────────
+
+// Drop the Claude-Code-only frontmatter keys, keep the rest of the frontmatter +
+// the entire body. Operates on the leading `---` … `---` block only; the body is
+// byte-preserved. Multi-line values (e.g. a wrapped description) are kept whole —
+// a dropped key's continuation lines (indented) are dropped with it.
+function translateFrontmatter(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!m) return content; // no frontmatter — pass through unchanged
+  const [, fm, body] = m;
+
+  const lines = fm.split('\n');
+  const kept = [];
+  let dropping = false;
+  for (const line of lines) {
+    const keyMatch = line.match(/^([A-Za-z0-9_-]+):/);
+    if (keyMatch) {
+      // a new top-level key — decide whether to drop it (+ its continuation)
+      dropping = DROP_KEYS.has(keyMatch[1]);
+      if (!dropping) kept.push(line);
+    } else if (!dropping) {
+      // continuation line of a kept key (indented / blank) — preserve
+      kept.push(line);
+    }
+    // else: continuation of a dropped key — skip
+  }
+  return `---\n${kept.join('\n')}\n---\n${body}`;
+}