create-evda 0.1.3 → 0.1.4

package/lib/tools.mjs

@@ -0,0 +1,274 @@
+// The record operations behind `evda mcp`: what an AI the owner already uses may do to their EVDA.
+//
+// Every tool here works on plain files on this machine. Nothing is sent anywhere and no model is
+// called. The AI that calls these tools is the owner's own (Claude Code, Codex, the Claude app);
+// EVDA holds no key and makes no request.
+//
+// Three rules hold for every write, and each has a test in test/tools.test.mjs:
+//   1. Append only. A write adds bytes to the end of a file or creates a new one. No tool takes a
+//      path to write to, and none replaces what is there.
+//   2. Nothing secret-shaped is written. The words are run through the same check that guards a
+//      reference (lib/references.mjs secretShape) and a hit refuses the whole write.
+//   3. Every write says where it landed, as a path relative to the record.
+//
+// A circle is never created here. `propose_circle` writes a proposal file for the owner to read;
+// making the circle, and granting anyone anything, stays the owner's explicit yes through
+// `evda grant` or their own hands.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { resolveRole, rolesForLayer, agentsFile } from "./roles.mjs";
+import { mdFiles, fileDate } from "./record.mjs";
+import { readCircles } from "./circles.mjs";
+import { secretShape } from "./references.mjs";
+import { doctor } from "./doctor.mjs";
+import { EvdaError } from "./errors.mjs";
+
+const pad = (n) => String(n).padStart(2, "0");
+export const localDate = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+export const localTime = (d) => `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const MAX_WORDS = 200_000;
+const MAX_READ = 256_000;
+
+function refuse(message, code = "REFUSED") {
+  return new EvdaError(`REFUSED: ${message} Nothing was written.`, { code, exit: 2 });
+}
+
+// Arguments a tool does not take are refused by name, so an agent that tries to pass a path or a
+// replacement learns the tool cannot do that, instead of the key being silently ignored.
+function onlyKeys(tool, args, allowed, hint = "") {
+  const extra = Object.keys(args ?? {}).filter((k) => !allowed.includes(k));
+  if (extra.length) throw refuse(`${tool} does not take ${extra.map((k) => JSON.stringify(k)).join(", ")}.${hint ? ` ${hint}` : ""}`, "UNKNOWN_ARGUMENT");
+}
+
+function text(value, name, tool) {
+  if (typeof value !== "string" || value.trim() === "") throw refuse(`${tool} needs "${name}", the text to file.`, "EMPTY");
+  if (value.length > MAX_WORDS) throw refuse(`${tool} "${name}" is ${value.length} characters; one write holds at most ${MAX_WORDS}.`, "TOO_LONG");
+  return value;
+}
+
+// Refuse the write when any line carries something shaped like a password, key or token. The value
+// is never echoed back: the message names the shape and the line number only.
+export function refuseSecrets(value, tool) {
+  const lines = value.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const shape = secretShape(lines[i]);
+    if (shape) throw refuse(`${tool}: line ${i + 1} holds ${shape}. A password, key or token is never written into the record; keep it in a password manager and point at the item with a reference.`, "SECRET");
+  }
+}
+
+function rel(evda, abs) {
+  return relative(evda.dir, abs).split("\\").join("/");
+}
+
+function dailyDir(evda) {
+  const r = resolveRole(evda, "record/daily");
+  if (!r.mapped) throw refuse('this record maps no "record/daily" role, so there is no daily file to append to.', "NO_ROLE");
+  return r;
+}
+
+// Where imports go: `imports/` beside the daily role, so `record/daily` gives `record/imports`, and
+// an adopted `journal/days` gives `journal/imports`.
+export function importsDir(evda) {
+  const r = dailyDir(evda);
+  return { abs: join(dirname(r.abs), "imports"), rel: join(dirname(r.rel), "imports").split("\\").join("/") };
+}
+
+// Proposals live at the record root, outside circles/ and grants/, so nothing that reads access
+// can mistake one for a decision.
+export const PROPOSALS = "proposals";
+
+// 1. The operating layer, whole. The first thing an agent reads.
+export function operatingLayer(evda, args = {}) {
+  onlyKeys("evda_operating_layer", args, []);
+  const a = agentsFile(evda);
+  if (!a) throw new EvdaError('this record maps no "agents" role, so it has no operating layer.', { code: "NO_ROLE" });
+  return { path: a.rel, text: readFileSync(a.abs, "utf8") };
+}
+
+// 2. The last `days` days of the record, newest first, whole files, capped in size. A file is in the
+// window by its date (filename, then a date or created key), the same rule `evda moment` uses.
+export function recent(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_recent", args, ["days"]);
+  const days = args.days === undefined ? 3 : Number(args.days);
+  if (!Number.isInteger(days) || days < 1 || days > 90) throw new EvdaError("evda_recent days must be a whole number from 1 to 90.", { code: "BAD_ARGUMENT", exit: 2 });
+  const start = new Date(now);
+  start.setDate(start.getDate() - (days - 1));
+  const from = localDate(start);
+  const to = localDate(now);
+  const files = [];
+  for (const abs of recordFiles(evda)) {
+    const body = readFileSync(abs, "utf8");
+    const date = fileDate(abs, body);
+    if (!date || date < from || date > to) continue;
+    files.push({ date, path: rel(evda, abs), text: body });
+  }
+  files.sort((a, b) => (a.date === b.date ? a.path.localeCompare(b.path) : b.date.localeCompare(a.date)));
+  let used = 0;
+  const out = [];
+  let truncated = 0;
+  for (const f of files) {
+    if (used + f.text.length > MAX_READ) { truncated += 1; continue; }
+    used += f.text.length;
+    out.push(f);
+  }
+  return { from, to, files: out, omitted: truncated };
+}
+
+// Every markdown file the record holds: each record-layer role, and the imports folder. Not the
+// ledger and not the operating layer; those have their own tools.
+function recordFiles(evda) {
+  const seen = new Set();
+  const out = [];
+  const add = (dir) => {
+    if (!dir || !existsSync(dir) || !statSync(dir).isDirectory()) return;
+    for (const p of mdFiles(dir)) if (!seen.has(p)) { seen.add(p); out.push(p); }
+  };
+  for (const role of rolesForLayer("record")) {
+    const r = resolveRole(evda, role);
+    if (r.mapped && r.exists && r.isDir) add(r.abs);
+  }
+  try { add(importsDir(evda).abs); } catch { /* no daily role, so no imports folder */ }
+  return out;
+}
+
+// 3. Append the owner's words, verbatim, to today's daily file, under the local time. Creates the
+// file with a date heading when it is the first write of the day. Returns the path.
+export function write(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_write", args, ["words"], "It appends to today's daily file and nothing else: it takes no path, and it never replaces or edits what is already written.");
+  const words = text(args.words, "words", "evda_write");
+  refuseSecrets(words, "evda_write");
+  const r = dailyDir(evda);
+  mkdirSync(r.abs, { recursive: true });
+  const date = localDate(now);
+  const abs = join(r.abs, `${date}.md`);
+  const head = existsSync(abs) ? "" : `# ${date}\n`;
+  const lead = existsSync(abs) && !readFileSync(abs, "utf8").endsWith("\n") ? "\n" : "";
+  appendFileSync(abs, `${lead}${head}\n## ${localTime(now)}\n\n${words.replace(/\n+$/, "")}\n`);
+  return { path: rel(evda, abs), bytes: Buffer.byteLength(words) };
+}
+
+// 4. File what another AI said about the owner, verbatim, under imports/, labeled with its source
+// and date. A second import from the same source on the same day is appended to that file.
+export function importText(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_import", args, ["text", "source", "date"], "It files a new import or appends to that day's import from the same source; it never edits one.");
+  const body = text(args.text, "text", "evda_import");
+  if (typeof args.source !== "string" || args.source.trim() === "") throw refuse('evda_import needs "source": which AI or app said this (ChatGPT, Claude, Gemini...).', "NO_SOURCE");
+  const source = args.source.trim().replace(/\s+/g, " ");
+  if (source.length > 60) throw refuse('evda_import "source" is a name, at most 60 characters.', "BAD_SOURCE");
+  const date = args.date === undefined ? localDate(now) : String(args.date);
+  if (!DATE.test(date)) throw refuse('evda_import "date" must be YYYY-MM-DD.', "BAD_DATE");
+  refuseSecrets(body, "evda_import");
+  refuseSecrets(source, "evda_import");
+  const dir = importsDir(evda);
+  mkdirSync(dir.abs, { recursive: true });
+  const slug = source.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "import";
+  const abs = join(dir.abs, `${date}-${slug}.md`);
+  const block = `\n## Imported ${localDate(now)} ${localTime(now)}\n\n${body.replace(/\n+$/, "")}\n`;
+  if (existsSync(abs)) appendFileSync(abs, block);
+  else {
+    writeFileSync(abs, [
+      `# Import from ${source}, ${date}`,
+      "",
+      `source: ${source}`,
+      `date: ${date}`,
+      "",
+      `What ${source} said about the owner, filed verbatim. These are not the owner's words. Each line is a claim to check with them over time, not a fact.`,
+      "",
+    ].join("\n") + block);
+  }
+  return { path: rel(evda, abs), bytes: Buffer.byteLength(body) };
+}
+
+// 5. Plain text search inside the record, on this machine. Case-insensitive substring over every
+// record file, the imports, and the ledger. Returns each matching line with its path and number.
+export function search(evda, args = {}) {
+  onlyKeys("evda_search", args, ["query", "limit"]);
+  if (typeof args.query !== "string" || args.query.trim() === "") throw new EvdaError('evda_search needs "query".', { code: "BAD_ARGUMENT", exit: 2 });
+  const limit = args.limit === undefined ? 50 : Number(args.limit);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new EvdaError("evda_search limit must be a whole number from 1 to 500.", { code: "BAD_ARGUMENT", exit: 2 });
+  const needle = args.query.toLowerCase();
+  const files = recordFiles(evda);
+  const ledger = resolveRole(evda, "ledger");
+  if (ledger.mapped && ledger.fileExists) files.push(ledger.file);
+  const matches = [];
+  let more = 0;
+  for (const abs of files) {
+    readFileSync(abs, "utf8").split("\n").forEach((line, i) => {
+      if (!line.toLowerCase().includes(needle)) return;
+      if (matches.length >= limit) { more += 1; return; }
+      matches.push({ path: rel(evda, abs), line: i + 1, text: line.length > 400 ? `${line.slice(0, 400)}...` : line });
+    });
+  }
+  return { query: args.query, searched: files.length, matches, more };
+}
+
+// 6. Circles and their policies, as the record declares them. Read only.
+export function circles(evda, args = {}) {
+  onlyKeys("evda_circles", args, []);
+  const all = readCircles(evda);
+  if (all === null) return { role: false, circles: [] };
+  return {
+    role: true,
+    circles: all.map((c) => ({
+      name: c.name,
+      path: c.rel,
+      public: c.manifest?.public ?? null,
+      description: c.manifest?.description ?? null,
+      maintainers: Array.isArray(c.manifest?.maintainers) ? c.manifest.maintainers.map((m) => m?.name).filter(Boolean) : [],
+      members: Object.keys(c.members),
+      policy: (c.policy?.rules ?? []).map((r) => ({ rule: r.rule, status: r.status, since: r.since })),
+      problems: c.problems.filter((p) => p.level === "fail").map((p) => p.message),
+    })),
+  };
+}
+
+// 7. Propose a circle. Writes one new file under proposals/ and nothing else: no circle directory,
+// no eco.yaml, no grant. The owner reads it and says yes or no.
+export function proposeCircle(evda, args = {}, { now = new Date() } = {}) {
+  onlyKeys("evda_propose_circle", args, ["name", "who", "what", "policy", "why"], "A proposal is a file for the owner to read. Creating the circle, adding a reader or moving an entry into it waits for their yes and is not done through this tool.");
+  const name = typeof args.name === "string" ? args.name.trim() : "";
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name)) throw refuse('evda_propose_circle "name" must be letters, digits, - and _ (it would name the circle folder).', "BAD_NAME");
+  const who = text(args.who, "who", "evda_propose_circle");
+  const what = text(args.what, "what", "evda_propose_circle");
+  const why = args.why === undefined ? "" : text(args.why, "why", "evda_propose_circle");
+  const policy = args.policy === undefined ? [] : args.policy;
+  if (!Array.isArray(policy) || policy.some((p) => typeof p !== "string" || p.trim() === "")) throw refuse('evda_propose_circle "policy" is a list of rules, one sentence each, in the owner\'s words.', "BAD_POLICY");
+  for (const s of [who, what, why, ...policy]) refuseSecrets(s, "evda_propose_circle");
+  const date = localDate(now);
+  const dir = join(evda.dir, PROPOSALS);
+  mkdirSync(dir, { recursive: true });
+  let abs = join(dir, `${date}-circle-${name}.md`);
+  for (let n = 2; existsSync(abs); n++) abs = join(dir, `${date}-circle-${name}-${n}.md`);
+  writeFileSync(abs, [
+    `# Proposed circle: ${name}`,
+    "",
+    `Proposed ${date}. Not a circle yet: nothing was created and nobody was granted anything. It becomes one only when the owner says yes.`,
+    "",
+    "## Who may read it",
+    "",
+    who.trim(),
+    "",
+    "## What it covers",
+    "",
+    what.trim(),
+    "",
+    "## Policy",
+    "",
+    ...(policy.length ? policy.map((p) => `- ${p.trim()}`) : ["(none proposed yet)"]),
+    "",
+    ...(why ? ["## Why", "", why.trim(), ""] : []),
+  ].join("\n"));
+  const circlesRole = resolveRole(evda, "circles");
+  return { path: rel(evda, abs), circleCreated: false, circlesRole: circlesRole.mapped ? circlesRole.rel : null };
+}
+
+// 8. evda doctor, captured. Exit 0 is well formed.
+export function doctorReport(evda, args = {}) {
+  onlyKeys("evda_doctor", args, []);
+  const lines = [];
+  const r = doctor(evda.dir, { out: (l) => lines.push(l), via: "evda mcp" });
+  return { exit: r.exit, text: lines.join("\n") };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-evda",
-  "version": "0.1.3",
-  "description": "Make your own EVÐA: a running journal of your life with Iris, as plain files on your machine, for any AI. No runtime dependencies.",
+  "version": "0.1.4",
+  "description": "Make your own EVÐA: a running journal of your life with Iris, as plain files on your machine, for any AI. Connect Claude Code, Codex or the Claude app over MCP. No runtime dependencies.",
   "type": "module",
   "bin": {
     "create-evda": "create-evda.mjs",
@@ -14,6 +14,7 @@
     "bin",
     "lib",
     "templates",
+    "skills",
     "migrations",
     "create-evda.mjs",
     "README.md",
@@ -23,7 +24,8 @@
     "evda",
     "personal-record",
     "agents",
-    "markdown"
+    "markdown",
+    "mcp"
   ],
   "author": "Mike Veson",
   "license": "MIT",

package/skills/evda/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: evda
+description: Use when the person talks to their EVÐA from Claude Code, Codex or the Claude app through the evda MCP server, or says "evda", "Iris", "my record", "journal this", "log this", or freewrites about their day, what is on their mind, a person, or something that felt off. Also use for the scheduled organize and look back routines. Acts as Iris through the evda_* tools, files their words verbatim, and never quizzes.
+---
+
+# EVÐA
+
+The person's EVÐA is their record: plain files on their machine, reached through the `evda` MCP
+server. You are the agent it describes (Iris unless they renamed you). EVÐA holds no API key and
+calls no model; you are their own AI, and everything you keep goes through the tools below.
+
+## Every session
+
+1. **Call `evda_operating_layer` first and follow it for the whole session.** It is who you are,
+   what this EVÐA is for in their words, how the record is kept, and what they have taught you.
+   Where it and this skill disagree, it wins.
+2. Call `evda_recent` for the last few days, and read what they point you at with `evda_search`.
+3. Say in one line what you read, then answer them.
+
+If the tools are not there, say so plainly and point them at `evda connect`, which prints the
+setup for each client. Do not keep the record some other way.
+
+## Keeping the record
+
+- **File their words in the same turn they say them**, with `evda_write`: verbatim, filler, hedges
+  and typos intact. Never a summary, never your words.
+- **Report every filing in the past tense, naming the path the tool returned.** Never "I'll file".
+- **`evda_write` only appends.** There is no edit and no rewrite. A correction is a new write.
+- **What another AI said about them is an import**, filed with `evda_import` and its source. It is
+  not their words: never quote it back as something they said. Each line is a claim to check.
+- **Never write a password, key or token.** The tools refuse one; tell them to keep it in their
+  password manager.
+
+## How to talk
+
+- **Never quiz them.** No lists of questions, no check-ins about open items, no "how did X go"
+  unless they bring it up. One real question when it helps, at most.
+- Take a position and show why; they push back and you get more specific. Never flatter.
+- Never cite a date, quote or event that is not in the record. Check with `evda_search` first.
+
+## Circles
+
+- Everything is private by default.
+- **Only when they ask to share something**, propose a circle with `evda_propose_circle`: who may
+  read it, what it covers, a short policy in their words. Tell them the proposal's path and wait.
+- **Never create a circle, grant anyone access, or move an entry into one.** That is their explicit
+  yes, done by them (`evda grant`), never by you.
+
+## Organizing (scheduled or asked)
+
+`evda organize` does the mechanical part itself: it copies each capture, verbatim, into the daily
+file of its date and writes a report under `reports/organize/`. With `--with-ai` it then asks you,
+through `claude -p`, for the part that needs judgment, and appends your answer to that report.
+
+When you are asked for that judgment:
+
+1. Read the report you are given, then use the read tools (`evda_recent`, `evda_search`,
+   `evda_circles`) to check each item against the record.
+2. For each note that needs a place, answer in one line: the note's path, where it belongs (a
+   person's file, a project, the ledger only if they already agreed to it), and the words from the
+   note that say so, quoted.
+3. You write nothing yourself here. Move nothing, rename nothing, delete nothing, and never touch
+   `circles/` or `grants/`. The owner reads the report and decides.
+4. If nothing needs a place, say that in one line.
+
+## Look back (weekly)
+
+Read the week with `evda_recent` (7 days). Write back, in a few lines, what recurred in their own
+words and what changed, quoting the file you took each from. No score, no streak, no grades, and
+no rule with a number in it. If nothing stands out, say that.