create-evda 0.1.8 → 0.1.10

package/hooks/evda-day-writer-guard.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook: on a machine with EVDA_DAY_WRITER set, refuse a direct write to the
+// record's daily file and send the agent to evda_write on the machine that writes it (HQ-2165). The
+// logic is lib/day-writer.mjs; this file is only the entry point a user-level settings.json names.
+import { runHook } from "../lib/day-writer.mjs";
+
+runHook().then((code) => process.exit(code), () => process.exit(0));

package/lib/acknowledge.mjs

@@ -0,0 +1,187 @@
+// Acknowledging what the owner put in the record (HQ-2060): the first reader to reach a weighty
+// entry says it back to them once, and every other reader can see that it did.
+//
+// THE PROBLEM. An owner learns how much something weighed from how it was received. Today every
+// agent over one record writes its own record and reads only its own: a live conversation, an
+// always-on agent, a scheduled run. So a correction the owner filed on Monday gets reacted to three
+// times, once by each, or zero times, because each assumes another already did. Mike, 2026-10-01:
+// "whoever sees it first acts on it whetehr its phroneiss or plan pass or a next session".
+//
+// WHERE THE MARK LIVES, AND WHY NOT ON THE ENTRY.
+//   - A record file is append only, and `evda_write` takes no path on purpose. The one tool that
+//     edits a file is `evda_release_note`, which edits one frontmatter line and only on the owner's
+//     explicit yes. A mark written into the entry would make every reader a writer of the owner's
+//     words.
+//   - The unit of weight is a section, not a file: one conversation is one `## HH:MM` inside a day
+//     file that holds several. Frontmatter cannot address a section.
+//   - Their words stay their words. A line the agent appends inside the day file is the agent's text
+//     in the owner's file, and a later reader can quote it back as something they said.
+// So the mark is a sidecar the readers share, in the shape `messages/.seen.json` already uses for
+// "what this agent has seen" (lib/messages.mjs): a dotfile of bookkeeping, keyed by what it tracks,
+// beside the thing it tracks. It is at the record root rather than under `.evda/`, because `.evda/`
+// is derived and rebuildable and an acknowledgement is derivable from nothing.
+//
+// The format, one file per record:
+//
+//   .acknowledged.json
+//     {
+//       "record/daily/2026-10-01.md#14:03": {
+//         "by": "Hestia",
+//         "at": "2026-10-01T06:12:00-04:00",
+//         "note": "said back to him that the Greek trade is settled and I will not reopen it"
+//       }
+//     }
+//
+// The key is the entry: its path relative to the record, and the exact heading of the section when
+// the weight is in one section. A heading never changes once written, so the key is stable.
+//
+// Append only, in the same sense as the record: a key that is present is never written over. The
+// second reader of an entry gets { first: false, already } and nothing is written, which is the
+// whole mechanism. "Weighty" is never decided here; weight is the reader's judgment and this file
+// only remembers that one of them acted.
+//
+// EVDA_ACK_FALSIFY=<mode,...>, for the tests. Each breaks exactly one rule:
+//   overwrite     a second acknowledgement of the same entry overwrites the first and reports first
+//   any-section   a section that is not a heading in that file is accepted
+//   strict-read   an .acknowledged.json that does not parse throws instead of reading as empty
+//   no-secrets    the secret check is skipped
+//   hide          acknowledgementsFor returns nothing, so a later reader cannot see the mark
+
+import { existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { agentName } from "./messages.mjs";
+import { secretShape } from "./references.mjs";
+import { isoLocal } from "./messages.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const ACK_FILE = ".acknowledged.json";
+export const NOTE_MAX = 400;
+export const BY_MAX = 60;
+export const SECTION_MAX = 200;
+
+export const ACK_FALSIFY_MODES = ["overwrite", "any-section", "strict-read", "no-secrets", "hide"];
+const falsified = (mode) => (process.env.EVDA_ACK_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+const refuse = (message, code) => new EvdaError(`REFUSED: ${message} Nothing was written.`, { code, exit: 2 });
+
+// The entry a mark is about: a path, and the section heading inside it when there is one.
+export function entryKey(path, section = null) {
+  const p = String(path).replace(/\\/g, "/").replace(/^\.\//, "");
+  return section ? `${p}#${section}` : p;
+}
+
+// A section as it is keyed: the heading's text, with its leading #s and surrounding space gone, so
+// "## 14:03", "##14:03" and "14:03" are one section.
+export function normalizeSection(section) {
+  return String(section).replace(/^\s*#+\s*/, "").trim();
+}
+
+function ackPath(evda) {
+  return join(evda.dir, ACK_FILE);
+}
+
+// Every mark this record holds, as { key: { by, at, note } }. Missing, unreadable, or not a JSON
+// object: empty, so a reader with no file acts like the first reader rather than throwing.
+export function readAcknowledged(evda) {
+  const p = ackPath(evda);
+  if (!existsSync(p)) return {};
+  let v;
+  try { v = JSON.parse(readFileSync(p, "utf8")); } catch (e) { if (falsified("strict-read")) throw e; return {}; }
+  if (v === null || typeof v !== "object" || Array.isArray(v)) return {};
+  const out = {};
+  for (const [k, m] of Object.entries(v)) {
+    if (m === null || typeof m !== "object" || Array.isArray(m)) continue;
+    if (typeof m.at !== "string" || typeof m.note !== "string") continue;
+    out[k] = { by: typeof m.by === "string" ? m.by : null, at: m.at, note: m.note };
+  }
+  return out;
+}
+
+function writeAcknowledged(evda, all) {
+  const p = ackPath(evda);
+  const keys = Object.keys(all).sort();
+  const ordered = Object.fromEntries(keys.map((k) => [k, all[k]]));
+  const t = `${p}.tmp-${process.pid}`;
+  writeFileSync(t, JSON.stringify(ordered, null, 2) + "\n");
+  renameSync(t, p);
+}
+
+// What is already acknowledged in one file, newest-written last: [{ section, by, at, note }]. A mark
+// on the file as a whole comes back with section null.
+export function acknowledgementsFor(path, all) {
+  if (falsified("hide")) return [];
+  const p = String(path).replace(/\\/g, "/");
+  const out = [];
+  for (const [key, m] of Object.entries(all)) {
+    const hash = key.indexOf("#");
+    const keyPath = hash === -1 ? key : key.slice(0, hash);
+    if (keyPath !== p) continue;
+    out.push({ section: hash === -1 ? null : key.slice(hash + 1), by: m.by, at: m.at, note: m.note });
+  }
+  out.sort((a, b) => String(a.section ?? "").localeCompare(String(b.section ?? "")));
+  return out;
+}
+
+// Is this entry already acknowledged? The read every other reader does before it says anything.
+export function isAcknowledged(evda, { path, section = null } = {}, all = null) {
+  const marks = all ?? readAcknowledged(evda);
+  const key = entryKey(path, section === null || section === undefined ? null : normalizeSection(section));
+  return marks[key] ?? null;
+}
+
+function oneLine(value, name, max) {
+  if (typeof value !== "string" || value.trim() === "") throw refuse(`evda_acknowledge needs "${name}".`, "EMPTY");
+  const v = value.trim();
+  if (/[\r\n]/.test(v)) throw refuse(`evda_acknowledge "${name}" is one line.`, "LINES");
+  if (v.length > max) throw refuse(`evda_acknowledge "${name}" is ${v.length} characters; at most ${max}.`, "TOO_LONG");
+  return v;
+}
+
+function refuseSecrets(value, name) {
+  if (falsified("no-secrets")) return;
+  const shape = secretShape(value);
+  if (shape) throw refuse(`evda_acknowledge "${name}" holds ${shape}. A password, key or token is never written into the record.`, "SECRET");
+}
+
+// Does `section` exist as a markdown heading in `text`?
+export function hasHeading(text, section) {
+  const want = normalizeSection(section);
+  return text.split("\n").some((line) => /^#{1,6}\s+/.test(line) && normalizeSection(line) === want);
+}
+
+// Record that this reader acted on one weighty entry. Returns
+// { key, path, section, first, by, at, note, already }.
+//
+// first true  : nothing was marked before, this reader is the one that acts, and the mark is written.
+// first false : another reader already did. Nothing is written, `already` says who, when and what
+//               they did, and this reader says nothing about the entry.
+export function acknowledge(evda, args = {}, { now = new Date() } = {}) {
+  if (typeof args.path !== "string" || args.path.trim() === "") throw refuse('evda_acknowledge needs "path", the entry in the record you acted on.', "NO_PATH");
+  const abs = resolve(evda.dir, args.path.trim());
+  if (abs !== evda.dir && !abs.startsWith(evda.dir + sep)) throw refuse(`${args.path} is outside the record.`, "OUTSIDE");
+  if (!existsSync(abs) || !statSync(abs).isFile()) throw refuse(`nothing is at ${args.path} in the record, so there is no entry to acknowledge.`, "MISSING");
+  const path = relative(evda.dir, abs).split(sep).join("/");
+
+  let section = null;
+  if (args.section !== undefined && args.section !== null && String(args.section).trim() !== "") {
+    section = normalizeSection(oneLine(String(args.section), "section", SECTION_MAX));
+    if (!falsified("any-section") && !hasHeading(readFileSync(abs, "utf8"), section)) {
+      throw refuse(`${path} has no heading "${section}". Acknowledge the heading as it is written in the file, or leave section out to acknowledge the whole entry.`, "NO_SECTION");
+    }
+  }
+
+  const key = entryKey(path, section);
+  const all = readAcknowledged(evda);
+  if (all[key] && !falsified("overwrite")) {
+    return { key, path, section, first: false, by: all[key].by, at: all[key].at, note: all[key].note, already: all[key] };
+  }
+
+  const note = oneLine(args.note, "note", NOTE_MAX);
+  refuseSecrets(note, "note");
+  const by = args.by === undefined || args.by === null ? agentName(evda) : oneLine(String(args.by), "by", BY_MAX);
+  refuseSecrets(by, "by");
+  const at = isoLocal(now);
+  all[key] = { by, at, note };
+  writeAcknowledged(evda, all);
+  return { key, path, section, first: true, by, at, note, already: null };
+}