create-evda 0.1.4 → 0.1.6

package/lib/presets.mjs

@@ -0,0 +1,379 @@
+// Presets: ways to organize a record, shipped as a library so an agent picks one instead of making
+// one up. Each is `presets/<id>/preset.json` in this package:
+//
+//   {
+//     "id": "journal",
+//     "title": "Journal",
+//     "for": "One sentence: who it suits.",
+//     "folders": [{ "path": "People", "type": "person", "connectors": ["contacts"], "note": "One file per person." }],
+//     "circles": [{ "name": "family", "public": false, "description": "...", "members": { "people": { "path": "People" } } }],
+//     "routines": ["weekly"],
+//     "mapping": { "journal": "Journal", "collections": "People" }
+//   }
+//
+// `mapping` is what the preset declares for the four roles (Spec 07 section 2, HQ-1371): each key
+// a role or a `<role>/<facet>`, each value a folder the preset makes. Every folder the preset makes
+// fills a role, by lying at or under one of these paths; a folder that fills none is refused, so
+// no preset ships a folder an agent cannot say the purpose of. Applying writes the role paths the
+// record does not have into its evda.json and never replaces a key it has: when the key is taken,
+// the folder fills the same role under a facet key named for it (`collections/people`).
+//
+// `folders` are paths relative to the record root. A folder with a `type` gets folder.evda.json
+// (type, connectors, views), checked by the same validator doctor uses; a folder with no type is a
+// plain directory and nothing more. `circles` are starter circles, in the substrate's eco shape with
+// members by path, and they are only ever PROPOSED: a proposal file under proposals/, never a circle.
+// `routines` name routines lib/routines.mjs already knows, and are offered, never scheduled.
+//
+// Applying a preset only adds. It creates the directories that are missing, writes the manifests
+// that are missing, and reports the rest: a manifest that already says the same thing is skipped,
+// one that says something else is a conflict and is left exactly as it is, and a preset path that
+// already exists as a file is a conflict. Nothing is moved, renamed or deleted, so applying twice
+// writes nothing the second time. A shipped preset that does not validate fails
+// test/presets.test.mjs, so the person running it never meets one.
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { openEvda, readManifest, writeManifest } from "./manifest.mjs";
+import { resolveRole, fourRoleOf, FOUR_ROLES, LEGACY_FACETS } from "./roles.mjs";
+import { validateFolderManifest, FOLDER_MANIFEST, FOLDER_TYPES } from "./folders.mjs";
+import { ROUTINE_KEYS } from "./routines.mjs";
+import { onlyKeys, proposeCircle, refuse, PROPOSALS } from "./tools.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const PRESETS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "presets");
+export const PRESET_FILE = "preset.json";
+export const PRESET_KEYS = ["id", "title", "for", "folders", "circles", "routines", "mapping"];
+export const PRESET_FOLDER_KEYS = ["path", "type", "connectors", "views", "note"];
+export const PRESET_CIRCLE_KEYS = ["name", "public", "description", "members"];
+export const NONE = "none";
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+const ID = /^[a-z0-9][a-z0-9-]*$/;
+const CIRCLE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+// A preset path: relative, forward slashes, no empty, dot or dot-dot segment, and no segment doctor's
+// walk would skip (a dot-directory or node_modules), because a folder doctor cannot see is a promise
+// nothing checks.
+function pathProblem(p) {
+  if (!nonEmpty(p)) return "must be a non-empty path";
+  if (p.includes("\\")) return "uses a backslash; paths use /";
+  if (p.startsWith("/")) return "is absolute; paths are relative to the record root";
+  for (const seg of p.split("/")) {
+    if (seg === "" || seg === "." || seg === "..") return `has an empty, . or .. segment`;
+    if (seg.startsWith(".") || seg === "node_modules") return `has the segment "${seg}", which doctor does not read`;
+  }
+  return null;
+}
+
+// Validate one preset. Returns a list of problem strings; empty is valid. Stricter than a folder
+// manifest on disk: an unknown key or type in something this package ships is a mistake, not a
+// newer tool's key to preserve.
+export function validatePreset(p, dirName = null) {
+  const problems = [];
+  const fail = (m) => problems.push(`${dirName ?? p?.id ?? "preset"}: ${m}`);
+  if (!isObject(p)) { fail("must hold a JSON object."); return problems; }
+  const unknown = Object.keys(p).filter((k) => !PRESET_KEYS.includes(k));
+  if (unknown.length) fail(`unknown key(s): ${unknown.join(", ")}.`);
+  if (!nonEmpty(p.id) || !ID.test(p.id)) fail(`"id" must be lowercase letters, digits and -, got ${JSON.stringify(p.id)}.`);
+  else if (dirName !== null && p.id !== dirName) fail(`"id" is ${JSON.stringify(p.id)} but the preset lives in ${dirName}/; the directory names it.`);
+  if (!nonEmpty(p.title)) fail(`"title" is missing.`);
+  if (!nonEmpty(p.for)) fail(`"for" is missing: one sentence saying who it suits.`);
+  else if (/\n/.test(p.for)) fail(`"for" is one sentence on one line.`);
+  const paths = new Set();
+  if (!Array.isArray(p.folders) || p.folders.length === 0) fail(`"folders" must be a non-empty list.`);
+  else {
+    p.folders.forEach((f, i) => {
+      const at = `folders[${i}]`;
+      if (!isObject(f)) { fail(`${at} must be { path, type?, connectors?, views?, note? }.`); return; }
+      const extra = Object.keys(f).filter((k) => !PRESET_FOLDER_KEYS.includes(k));
+      if (extra.length) fail(`${at} unknown key(s): ${extra.join(", ")}.`);
+      const bad = pathProblem(f.path);
+      if (bad) { fail(`${at} path ${bad}.`); return; }
+      if (paths.has(f.path)) fail(`${at} path ${f.path} is listed twice.`);
+      paths.add(f.path);
+      if (f.note !== undefined && !nonEmpty(f.note)) fail(`${at} "note" must be a sentence.`);
+      if (f.type === undefined) {
+        if (f.connectors !== undefined || f.views !== undefined) fail(`${at} (${f.path}) has connectors or views and no type. An untyped folder is a plain directory with no manifest to hold them.`);
+        return;
+      }
+      if (!FOLDER_TYPES.includes(f.type)) fail(`${at} (${f.path}) type ${JSON.stringify(f.type)} is not one of ${FOLDER_TYPES.join(", ")}.`);
+      const v = validateFolderManifest(manifestFor(f), `${f.path}/${FOLDER_MANIFEST}`);
+      for (const pr of v.problems) fail(pr.message);
+      for (const view of f.views ?? []) {
+        if (isObject(view) && nonEmpty(view.path) && pathProblem(view.path)) fail(`${at} view "${view.view}" path ${pathProblem(view.path)}.`);
+      }
+    });
+  }
+  // The four roles. Required: a preset is a way to fill them.
+  if (!isObject(p.mapping) || Object.keys(p.mapping).length === 0) fail(`"mapping" must name the folders that fill the four roles (${FOUR_ROLES.join(", ")}).`);
+  else {
+    const rolePaths = [];
+    for (const [key, rel] of Object.entries(p.mapping)) {
+      const role = fourRoleOf(key);
+      if (!role || LEGACY_FACETS[key]) { fail(`mapping key "${key}" is not one of the four roles or a <role>/<facet> of one.`); continue; }
+      if (!nonEmpty(rel) || !paths.has(rel)) { fail(`mapping "${key}" is ${JSON.stringify(rel)}, which is not a folder this preset makes.`); continue; }
+      rolePaths.push({ role, rel });
+    }
+    const missing = FOUR_ROLES.filter((r) => !rolePaths.some((x) => x.role === r));
+    if (missing.length) fail(`fills no folder for ${missing.join(", ")}. Every record has the four roles.`);
+    for (const fp of paths) {
+      if (!rolePaths.some((x) => fp === x.rel || fp.startsWith(`${x.rel}/`))) fail(`folder ${fp} fills no role: it is not at or under any path in "mapping".`);
+    }
+    const seen = new Map();
+    for (const x of rolePaths) { if (seen.has(x.rel) && seen.get(x.rel) !== x.role) fail(`folder ${x.rel} fills two roles.`); seen.set(x.rel, x.role); }
+  }
+  if (p.circles !== undefined) {
+    if (!Array.isArray(p.circles)) fail(`"circles" must be a list.`);
+    else {
+      const names = new Set();
+      p.circles.forEach((c, i) => {
+        const at = `circles[${i}]`;
+        if (!isObject(c)) { fail(`${at} must be { name, public, description, members }.`); return; }
+        const extra = Object.keys(c).filter((k) => !PRESET_CIRCLE_KEYS.includes(k));
+        if (extra.length) fail(`${at} unknown key(s): ${extra.join(", ")}.`);
+        if (!nonEmpty(c.name) || !CIRCLE_NAME.test(c.name)) fail(`${at} "name" must be letters, digits, - and _.`);
+        else if (names.has(c.name)) fail(`${at} circle ${c.name} is listed twice.`);
+        else names.add(c.name);
+        if (typeof c.public !== "boolean") fail(`${at} "public" must be true or false.`);
+        if (!nonEmpty(c.description)) fail(`${at} "description" says in plain words who may read it and why.`);
+        if (!isObject(c.members) || Object.keys(c.members).length === 0) { fail(`${at} "members" must name at least one path.`); return; }
+        for (const [name, m] of Object.entries(c.members)) {
+          if (!isObject(m) || Object.keys(m).length !== 1 || !nonEmpty(m.path)) { fail(`${at} member "${name}" must be { path }; a preset circle holds folders this preset makes.`); continue; }
+          if (![...paths].some((fp) => m.path === fp || m.path.startsWith(`${fp}/`))) fail(`${at} member "${name}" path ${m.path} is not a folder this preset makes.`);
+        }
+      });
+    }
+  }
+  if (p.routines !== undefined) {
+    if (!Array.isArray(p.routines)) fail(`"routines" must be a list.`);
+    else {
+      for (const r of p.routines) if (!ROUTINE_KEYS.includes(r)) fail(`routine ${JSON.stringify(r)} is not one this package has (${ROUTINE_KEYS.join(", ")}).`);
+      if (new Set(p.routines).size !== p.routines.length) fail(`"routines" lists one twice.`);
+    }
+  }
+  return problems;
+}
+
+// The folder.evda.json a typed preset folder writes. The same three keys the scaffold writes.
+export function manifestFor(folder) {
+  return { type: folder.type, connectors: folder.connectors ?? [], views: folder.views ?? [] };
+}
+
+// Read one preset from `dir` (the presets directory). Throws when it is missing or does not validate.
+export function loadPreset(id, { dir = PRESETS_DIR } = {}) {
+  if (!nonEmpty(id) || !ID.test(id)) throw new EvdaError(`REFUSED: ${JSON.stringify(id)} is not a preset id. Presets: ${presetIds({ dir }).join(", ")}.`, { code: "NO_PRESET", exit: 2 });
+  const p = join(dir, id, PRESET_FILE);
+  if (!existsSync(p)) throw new EvdaError(`REFUSED: no preset named "${id}". Presets: ${presetIds({ dir }).join(", ")}.`, { code: "NO_PRESET", exit: 2 });
+  let preset;
+  try {
+    preset = JSON.parse(readFileSync(p, "utf8"));
+  } catch (e) {
+    throw new EvdaError(`REFUSED: preset ${id} is not valid JSON (${e.message}).`, { code: "BAD_PRESET", exit: 2 });
+  }
+  const problems = validatePreset(preset, id);
+  if (problems.length) throw new EvdaError(`REFUSED: preset ${id} is malformed: ${problems[0]}`, { code: "BAD_PRESET", exit: 2 });
+  return preset;
+}
+
+export function presetIds({ dir = PRESETS_DIR } = {}) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((n) => !n.startsWith(".") && existsSync(join(dir, n, PRESET_FILE))).sort();
+}
+
+// Every shipped preset, loaded and validated.
+export function listPresets(opts = {}) {
+  return presetIds(opts).map((id) => loadPreset(id, opts));
+}
+
+// What `folder`'s existing manifest lacks against the preset's: a different type, a connector or a
+// view the preset declares and it does not. [] means it already says what the preset says; a
+// connector or view the owner added beyond the preset is theirs and is not a difference.
+function differences(existing, want) {
+  const out = [];
+  if (!isObject(existing)) return ["it does not hold a JSON object"];
+  if (existing.type !== want.type) out.push(`its type is ${JSON.stringify(existing.type)}, the preset's is "${want.type}"`);
+  const has = Array.isArray(existing.connectors) ? existing.connectors : [];
+  const missing = want.connectors.filter((c) => !has.includes(c));
+  if (missing.length) out.push(`it does not declare connector(s) ${missing.join(", ")}`);
+  const views = Array.isArray(existing.views) ? existing.views.map((v) => v?.view) : [];
+  const noView = want.views.filter((v) => !views.includes(v.view)).map((v) => v.view);
+  if (noView.length) out.push(`it does not declare view(s) ${noView.join(", ")}`);
+  return out;
+}
+
+// The first segment of `rel` that exists and is not a directory, or null.
+function blockedBy(root, rel) {
+  const segs = rel.split("/");
+  for (let i = 1; i <= segs.length; i++) {
+    const sub = segs.slice(0, i).join("/");
+    const abs = join(root, sub);
+    let st;
+    try { st = lstatSync(abs); } catch { return null; }
+    if (st.isSymbolicLink()) { try { st = statSync(abs); } catch { return sub; } }
+    if (!st.isDirectory()) return sub;
+  }
+  return null;
+}
+
+const viewHeader = (v) => ["---", `view: ${v.view}`, `of: ${v.of}`, `in: ${v.in}`, "---", ""].join("\n");
+
+// The plan for applying preset `id` to the record at `root`, and with `dry: false` the writes.
+//   create     directories that do not exist yet
+//   write      manifests that do not exist yet ({ path, folder, manifest })
+//   views      view files a manifest declares that do not exist yet
+//   matched    manifests that exist and already say what the preset says (skipped)
+//   conflicts  manifests that exist and say something else, and preset paths that are files
+//              ({ path, why }); reported, never overwritten
+//   circles    preset circles with no circle and no proposal yet, proposed on apply
+//   routines   routines the preset suggests, offered and never scheduled
+export function applyPreset(root, id, { dry = false, now = new Date(), dir = PRESETS_DIR } = {}) {
+  const evda = openEvda(resolve(root));
+  const preset = loadPreset(id, { dir });
+  const plan = { id: preset.id, title: preset.title, root: evda.dir, dry, create: [], write: [], views: [], matched: [], conflicts: [], circles: [], proposed: [], routines: preset.routines ?? [], folders: preset.folders.length, roles: [] };
+  // The four roles the record does not declare yet. A key it has with another path is a conflict,
+  // left as it is; a path it already maps under a key of the same role is already there.
+  const has = evda.manifest.mapping;
+  for (const [key, rel] of Object.entries(preset.mapping ?? {})) {
+    if (has[key] === rel) continue;
+    if (Object.entries(has).some(([k, v]) => v === rel && fourRoleOf(k) === fourRoleOf(key))) continue;
+    // A key the record already uses for another path keeps it; the preset's folder fills the same
+    // role under a facet key named for the folder, so two presets compose and nothing is replaced.
+    let k = key;
+    if (has[k] !== undefined || plan.roles.some((r) => r.key === k)) {
+      const slug = rel.split("/").pop().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "folder";
+      k = `${fourRoleOf(key)}/${slug}`;
+      for (let n = 2; has[k] !== undefined || plan.roles.some((r) => r.key === k); n++) k = `${fourRoleOf(key)}/${slug}-${n}`;
+    }
+    plan.roles.push({ key: k, rel });
+  }
+  const blocked = new Set();
+  for (const f of preset.folders) {
+    const abs = resolve(evda.dir, f.path);
+    if (!abs.startsWith(evda.dir + sep)) { plan.conflicts.push({ path: f.path, why: "resolves outside the record" }); continue; }
+    const file = blockedBy(evda.dir, f.path);
+    if (file) {
+      if (!blocked.has(file)) plan.conflicts.push({ path: file, why: `exists as a file, so the folder ${f.path} cannot be made there` });
+      blocked.add(file);
+      continue;
+    }
+    if (!existsSync(abs) && !plan.create.includes(f.path)) plan.create.push(f.path);
+    if (f.type === undefined) continue;
+    const want = manifestFor(f);
+    const mpath = `${f.path}/${FOLDER_MANIFEST}`;
+    const mabs = join(abs, FOLDER_MANIFEST);
+    if (!existsSync(mabs)) plan.write.push({ path: mpath, folder: f, manifest: want });
+    else if (!lstatSync(mabs).isFile()) plan.conflicts.push({ path: mpath, why: "exists and is not a file" });
+    else {
+      let existing;
+      try { existing = JSON.parse(readFileSync(mabs, "utf8")); } catch { plan.conflicts.push({ path: mpath, why: "exists and is not valid JSON" }); continue; }
+      const diff = differences(existing, want);
+      if (diff.length) plan.conflicts.push({ path: mpath, why: `exists and differs: ${diff.join("; ")}` });
+      else plan.matched.push({ path: mpath });
+    }
+    for (const v of want.views) {
+      if (!existsSync(resolve(evda.dir, v.path))) plan.views.push({ path: v.path, view: v });
+    }
+  }
+  // A role is declared only over a folder this apply leaves in place; one a file blocks is not.
+  plan.roles = plan.roles.filter((r) => blockedBy(evda.dir, r.rel) === null);
+  const circlesRole = resolveRole(evda, "circles");
+  const proposals = join(evda.dir, PROPOSALS);
+  const proposalNames = existsSync(proposals) ? readdirSync(proposals) : [];
+  for (const c of preset.circles ?? []) {
+    const exists = circlesRole.mapped && existsSync(join(circlesRole.abs, c.name));
+    const proposed = proposalNames.some((n) => new RegExp(`^\\d{4}-\\d{2}-\\d{2}-circle-${c.name}(-\\d+)?\\.md$`).test(n));
+    if (!exists && !proposed) plan.circles.push(c);
+  }
+  if (dry) return plan;
+
+  if (plan.roles.length) {
+    const m = readManifest(evda.dir);
+    for (const r of plan.roles) m.mapping[r.key] ??= r.rel;
+    writeManifest(evda.dir, m);
+  }
+  for (const rel of plan.create) mkdirSync(join(evda.dir, rel), { recursive: true });
+  for (const w of plan.write) writeFileSync(join(evda.dir, w.path), JSON.stringify(w.manifest, null, 2) + "\n", { flag: "wx" });
+  for (const v of plan.views) {
+    mkdirSync(dirname(resolve(evda.dir, v.path)), { recursive: true });
+    writeFileSync(resolve(evda.dir, v.path), viewHeader(v.view), { flag: "wx" });
+  }
+  for (const c of plan.circles) {
+    const r = proposeCircle(evda, {
+      name: c.name,
+      who: c.public ? "Anyone." : "Only the people the owner grants it to, by name.",
+      what: Object.values(c.members).map((m) => m.path).join(", "),
+      why: `${c.description} Suggested by the ${preset.title} preset.`,
+    }, { now });
+    plan.proposed.push(r.path);
+  }
+  return plan;
+}
+
+// What preset `id` has that the record at `root` does not: the dry-run plan, which by construction
+// holds only additions and conflicts. This is how an agent proposes one folder from the library later.
+export function diffPreset(root, id, opts = {}) {
+  return applyPreset(root, id, { ...opts, dry: true });
+}
+
+export const planIsEmpty = (plan) => !plan.create.length && !plan.write.length && !plan.views.length && !plan.circles.length && !plan.conflicts.length && !(plan.roles ?? []).length;
+
+// The plan in plain words, for the owner to say yes or no to. Names each folder by its note.
+export function summary(plan, preset = loadPreset(plan.id)) {
+  const lines = [];
+  const adds = preset.folders.filter((f) => plan.create.includes(f.path) || plan.write.some((w) => w.folder.path === f.path));
+  if (!adds.length && !plan.circles.length && !plan.conflicts.length && !(plan.roles ?? []).length) {
+    lines.push(`This record already has everything the ${plan.title} preset makes. Nothing would be written.`);
+  } else {
+    lines.push(`The ${plan.title} preset would add ${adds.length} folder(s) to this record:`);
+    for (const f of adds) lines.push(`- ${f.path}/${f.type ? ` (${f.type})` : ""}${f.note ? `: ${f.note}` : ""}`);
+    if (plan.roles?.length) lines.push(`It would declare ${plan.roles.length} role path(s) in evda.json: ${plan.roles.map((r) => `${r.key} -> ${r.rel}`).join(", ")}.`);
+    if (plan.circles.length) lines.push(`It would propose ${plan.circles.length} circle(s), as proposal files only: ${plan.circles.map((c) => c.name).join(", ")}.`);
+    if (plan.matched.length) lines.push(`${plan.matched.length} folder(s) are already set up the same way and would be left alone.`);
+    for (const c of plan.conflicts) lines.push(`Left as it is: ${c.path} ${c.why}.`);
+    lines.push("Nothing is moved, renamed or deleted. It is applied only when the owner says yes.");
+  }
+  if (plan.routines.length) lines.push(`It suits the ${plan.routines.join(" and ")} routine(s), offered separately and never scheduled without a yes.`);
+  return lines.join("\n");
+}
+
+// Plan lines for the CLI, in the package's CHECKED / SKIPPED convention.
+export function planLines(plan, { diff = false } = {}) {
+  const out = [];
+  const verb = plan.dry || diff ? "would" : "did";
+  for (const p of plan.create) out.push(`  ${verb === "did" ? "created " : "create  "} ${p}/`);
+  for (const w of plan.write) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${w.path}  type ${w.manifest.type}${w.manifest.connectors.length ? `, connectors ${w.manifest.connectors.join(", ")}` : ""}`);
+  for (const r of plan.roles ?? []) out.push(`  ${verb === "did" ? "declared" : "declare "} ${r.key} -> ${r.rel}  in evda.json`);
+  for (const v of plan.views) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${v.path}  view ${v.view.view} (header only)`);
+  if (!diff) for (const m of plan.matched) out.push(`  skipped  ${m.path}  already says the same`);
+  for (const c of plan.conflicts) out.push(`  CONFLICT ${c.path}  ${c.why}. Left as it is.`);
+  if (plan.proposed.length) for (const p of plan.proposed) out.push(`  proposed ${p}  (a proposal file; no circle was created)`);
+  else for (const c of plan.circles) out.push(`  propose  circle ${c.name}  (a proposal file only)`);
+  for (const r of plan.routines) out.push(`  offer    routine ${r}: evda routine ${r}  (nothing is scheduled without a yes)`);
+  return out;
+}
+
+// The MCP tools. Each takes the open record and its arguments, and refuses an argument it does not take.
+
+export function presetsTool(evda, args = {}) {
+  onlyKeys("evda_presets", args, ["id"]);
+  if (args.id === undefined) return { presets: listPresets().map((p) => ({ id: p.id, title: p.title, for: p.for, folders: p.folders.length })) };
+  return { preset: loadPreset(args.id) };
+}
+
+export function proposeStructureTool(evda, args = {}) {
+  onlyKeys("evda_propose_structure", args, ["id"], "It only proposes. Applying a preset is evda_apply_preset, after the owner says yes.");
+  if (!nonEmpty(args.id)) throw refuse(`evda_propose_structure needs "id", a preset from evda_presets.`, "NO_PRESET");
+  const plan = applyPreset(evda.dir, args.id, { dry: true });
+  return { plan, summary: summary(plan) };
+}
+
+export function applyPresetTool(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_apply_preset", args, ["id", "confirmed"], "It adds the preset's folders and manifests and nothing else; it never moves, renames or deletes.");
+  if (!nonEmpty(args.id)) throw refuse(`evda_apply_preset needs "id", a preset from evda_presets.`, "NO_PRESET");
+  if (args.confirmed !== true) throw refuse(`evda_apply_preset needs "confirmed": true, and that is true only when the owner said yes to this preset in this conversation. Show them evda_propose_structure first and wait.`, "NOT_CONFIRMED");
+  loadPreset(args.id);
+  const plan = applyPreset(evda.dir, args.id, { now });
+  return { plan, lines: planLines(plan) };
+}

package/lib/prompt-hook.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Every message the owner sends, filed, in Claude Code (HQ-1385): a UserPromptSubmit hook that
+// appends each prompt verbatim to the day's record, deterministically, before the model sees it.
+//
+// Mike, 2026-09-22, asked what the Claude app files: "Everything... how we can make this even more
+// sustainable so that I can do this for all of the users." A tool description and an instruction
+// are prompts, and a model can ignore both; a hook cannot be ignored. It exists only for an owner who
+// answered "everything" to the one setup question: it reads evda.json `filing` on every call and
+// files nothing when it says anything else, and `evda hook install` installs it only then.
+//
+// The append is lib/day-file.mjs appendToDay, the path evda_write uses: the first prompt of a
+// session opens `## HH:MM`, later ones go under it. The session is Claude Code's session_id, kept
+// in a small state file outside the record. A prompt holding something shaped like a password, key
+// or token is not filed (lib/secret-shape.mjs, the check evda_write makes); a slash command is not
+// the owner's words and is not filed.
+//
+// What it prints is added to the model's context: one line naming the file, so the model does not
+// file the same words again with evda_write.
+//
+// Copied byte for byte into <record>/.claude/hooks/evda-file-prompt.mjs beside day-file.mjs and
+// secret-shape.mjs. Any error of its own exits 0 with no output: a broken hook must never block the
+// owner's message.
+//
+// EVDA_CHAT_FALSIFY=ignore-filing files even when evda.json does not say "everything", for the test
+// that shows the hook reads the owner's answer.
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dayRole, findRecord, filingOf, appendToDay, localDate } from "./day-file.mjs";
+import { secretShape } from "./secret-shape.mjs";
+
+export const PROMPT_HOOK_NAME = "evda-file-prompt.mjs";
+
+const falsified = (mode) => (process.env.EVDA_CHAT_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+function stateFile(sid) {
+  const dir = process.env.EVDA_PROMPT_STATE_DIR || join(tmpdir(), "evda-file-prompt");
+  mkdirSync(dir, { recursive: true });
+  return join(dir, `${String(sid).replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+}
+
+// One UserPromptSubmit event in, the hook's stdout out ("" for nothing to say). Never throws.
+export function run(payload, { now = new Date() } = {}) {
+  try {
+    const prompt = typeof payload?.prompt === "string" ? payload.prompt : "";
+    if (!prompt.trim() || /^\s*\//.test(prompt)) return "";
+    const here = dirname(fileURLToPath(import.meta.url));
+    const root = findRecord(payload.cwd || process.cwd()) ?? findRecord(here);
+    if (!root) return "";
+    const manifest = JSON.parse(readFileSync(join(root, "evda.json"), "utf8"));
+    if (filingOf(manifest) !== "everything" && !falsified("ignore-filing")) return "";
+    const role = dayRole(manifest.mapping ?? {});
+    if (!role) return "";
+    const shape = prompt.split("\n").map(secretShape).find(Boolean);
+    if (shape) return `evda: this message was not filed, because it holds ${shape}. Keep that in a password manager; file the rest of what they said with evda_write if it is worth keeping.`;
+    const dayAbs = join(root, manifest.mapping[role].replace(/\/+$/, ""));
+    mkdirSync(dayAbs, { recursive: true });
+    const abs = join(dayAbs, `${localDate(now)}.md`);
+    const sf = stateFile(payload.session_id ?? "unknown");
+    let session = {};
+    try { session = JSON.parse(readFileSync(sf, "utf8")); } catch { /* the first prompt of the session */ }
+    appendToDay(abs, { now, words: prompt, session });
+    writeFileSync(sf, JSON.stringify(session) + "\n");
+    const rel = relative(root, abs).split("\\").join("/");
+    return `evda: the owner's message above is already filed verbatim in ${rel}. Do not file it again with evda_write.`;
+  } catch {
+    return "";
+  }
+}
+
+const entry = (() => {
+  try { return process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+})();
+
+if (entry && existsSync(process.argv[1])) {
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (d) => (input += d));
+  process.stdin.on("end", () => {
+    let payload = null;
+    try { payload = JSON.parse(input); } catch { /* not a hook call */ }
+    const out = run(payload);
+    if (out) process.stdout.write(out);
+    process.exit(0);
+  });
+}