create-evda 0.1.4 → 0.1.6

package/lib/yaml.mjs

@@ -2,7 +2,8 @@
 //
 // The substrate writes an eco as `eco.yaml`, and this package has no runtime dependencies, so the
 // subset of YAML an eco manifest uses is read and written here: comments, block mappings, block
-// sequences, plain and quoted scalars, block scalars (`|`, `>`), and one level of flow collections.
+// sequences, plain and quoted scalars, block scalars (`|`, `>`, with chomping and indentation
+// indicators), and one level of flow collections.
 // Anchors, aliases, tags, multi-document streams and tab indentation are refused with a line
 // number rather than guessed at. `test/yaml.test.mjs` checks this reader against the `yaml`
 // package over the substrate's own manifests, so the two agree on every file that matters.
@@ -48,6 +49,13 @@ function lines(text) {
   return out;
 }
 
+// Set a parsed key as an own property. A plain `out[key] = v` treats "__proto__" as the prototype,
+// and `key in out` finds "toString" and "constructor" on every object, so a frontmatter key named
+// like an Object method read as a duplicate (HQ-1406).
+function put(out, key, value) {
+  Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
+}
+
 const PLAIN_BOOL = { true: true, false: false, True: true, False: false, TRUE: true, FALSE: false };
 const NULLS = new Set(["null", "Null", "NULL", "~", ""]);
 
@@ -125,7 +133,7 @@ function flow(t, no) {
         skip();
         if (peek() !== ":") fail(no, "expected : in flow mapping");
         i++;
-        out[String(k)] = value();
+        put(out, String(k), value(), no);
         skip();
         if (peek() === ",") { i++; continue; }
         if (peek() === "}") { i++; return out; }
@@ -147,8 +155,10 @@ function splitKey(text, no) {
   let key;
   if (text[0] === '"' || text[0] === "'") {
     const q = text[0];
+    // An escaped quote inside a double-quoted key does not end it: the writer quotes a key with
+    // JSON.stringify, so `"a\"b"` is one key (HQ-1406).
     let j = 1;
-    while (j < text.length && text[j] !== q) j++;
+    while (j < text.length && text[j] !== q) j += q === '"' && text[j] === "\\" ? 2 : 1;
     if (j >= text.length) fail(no, "unterminated quoted key");
     key = scalar(text.slice(0, j + 1), no);
     i = j + 1;
@@ -162,39 +172,92 @@ function splitKey(text, no) {
   return { key: String(key), rest: text.slice(i + 1).trim() };
 }
 
-function blockScalar(header, ls, i, parentIndent, no) {
-  const m = /^([|>])([-+]?)$/.exec(header);
+// A block scalar (`|` or `>`) is read from the raw text lines, not from lines(): its body keeps
+// what lines() drops, a `#` line, a leading or trailing blank line, a whitespace-only line (HQ-1409).
+// YAML 1.2 rules: the indentation is the header's indicator over the parent's, or else the first
+// non-blank line's; the body ends at the first non-blank line indented less; `>` folds a line break
+// between two lines that do not start with whitespace; `-` strips the final newlines, `+` keeps
+// them all, and the default keeps one. Where the spec leaves a corner open (a whitespace-only line
+// at the end, a text with no final line break) this reads it as the `yaml` package does, since
+// every other tool that reads these files uses it. `src` is the text's lines, `no` the header's.
+function blockScalar(header, ls, i, parentIndent, no, src) {
+  const m = /^([|>])(?:([-+]?)([1-9]?)|([1-9])([-+]))$/.exec(header);
   if (!m) fail(no, `unsupported block scalar header ${header}`);
   const fold = m[1] === ">";
-  const chomp = m[2];
-  const body = [];
-  let j = i;
-  let blockIndent = null;
-  while (j < ls.length && ls[j].indent > parentIndent) {
-    if (blockIndent === null) blockIndent = ls[j].indent;
-    body.push({ text: ls[j].raw.slice(blockIndent), blank: false, no: ls[j].no });
-    j++;
+  const chomp = m[2] || m[5] || "";
+  const indicator = Number(m[3] || m[4] || 0);
+  // The text's final line break ends its last line; it does not open another one.
+  const last = src.length > 0 && src[src.length - 1].replace(/\r$/, "") === "" ? src.length - 1 : src.length;
+  const raw = (k) => src[k].replace(/\r$/, "");
+  const spaces = (l) => l.length - l.replace(/^ +/, "").length;
+  const blank = (l) => /^ *$/.test(l);
+  let first = null; // the first non-blank line's indentation
+  for (let k = no; k < last; k++) {
+    const l = raw(k);
+    if (blank(l)) continue;
+    if (spaces(l) > parentIndent) first = spaces(l);
+    break;
+  }
+  // With no content line, every line up to the next less-indented one is blank, however long.
+  const indent = indicator ? parentIndent + indicator : first ?? Infinity;
+  const lines = []; // each line: its text past the indentation, or null when blank
+  let k = no;
+  for (; k < last; k++) {
+    const l = raw(k);
+    if (blank(l)) { lines.push({ text: l.length > indent ? l.slice(indent) : null, len: l.length }); continue; }
+    if (spaces(l) < indent) {
+      if (/^ *\t/.test(l)) fail(k + 1, "tab indentation");
+      break;
+    }
+    lines.push({ text: l.slice(indent), len: l.length });
+  }
+  const open = k === last && last === src.length; // the block ends the text, with no final line break
+  const hasContent = lines.some((l) => l.text !== null && !blank(l.text));
+  if (!hasContent) {
+    if (chomp !== "+" || lines.length === 0) return done("");
+    return done("\n".repeat(Math.max(1, lines.length - (open ? 1 : 0))));
+  }
+  // YAML refuses a leading blank line indented past the block, since it would decide the indentation.
+  if (!indicator) {
+    for (let b = 0; b < lines.length && (lines[b].text === null || blank(lines[b].text)); b++) {
+      if (lines[b].text !== null) fail(no + b + 1, "a leading all-space line is indented past the block; give the header an indentation indicator");
+    }
   }
-  // Blank lines inside a block scalar were dropped by lines(); recover them from line numbers.
-  const withBlanks = [];
-  for (let k = 0; k < body.length; k++) {
-    if (k > 0) for (let g = body[k - 1].no + 1; g < body[k].no; g++) withBlanks.push("");
-    withBlanks.push(body[k].text);
+  // Without `+`, a whitespace-only last line no longer than the first content line is not content.
+  let end = lines.length;
+  for (;;) {
+    while (end > 0 && lines[end - 1].text === null) end--;
+    if (chomp !== "+" && end > 0 && blank(lines[end - 1].text) && lines[end - 1].len <= first) { lines[--end].text = null; continue; }
+    break;
   }
-  let text;
+  const content = lines.slice(0, end).map((l) => l.text ?? "");
+  let text = "";
   if (fold) {
-    text = withBlanks.reduce((acc, l, k) => {
-      if (k === 0) return l;
-      if (l === "") return acc + "\n";
-      return acc.endsWith("\n") ? acc + l : acc + " " + l;
-    }, "");
+    const moreIndented = (l) => /^[ \t]/.test(l);
+    let prev = null;
+    let empties = 0;
+    for (const l of content) {
+      if (l === "") { empties++; continue; }
+      if (prev === null) text += "\n".repeat(empties);
+      else if (!moreIndented(prev) && !moreIndented(l)) text += empties === 0 ? " " : "\n".repeat(empties);
+      else text += "\n".repeat(empties + 1);
+      text += l;
+      prev = l;
+      empties = 0;
+    }
   } else {
-    text = withBlanks.join("\n");
+    text = content.join("\n");
+  }
+  if (chomp === "-") return done(text);
+  if (chomp === "") return done(text + "\n");
+  // `+` keeps the content line's break and one per blank line after it that ends in a line break.
+  return done(text + "\n" + "\n".repeat(Math.max(0, lines.length - end - (open ? 1 : 0))));
+
+  function done(value) {
+    let j = i;
+    while (j < ls.length && ls[j].no <= k) j++;
+    return { value, next: j };
   }
-  if (chomp === "-") text = text.replace(/\n+$/, "");
-  else if (chomp === "+") text = text + "\n";
-  else text = text.replace(/\n+$/, "") + "\n";
-  return { value: text, next: j };
 }
 
 function parseBlock(ls, i, indent) {
@@ -220,7 +283,7 @@ function parseSeq(ls, i, indent) {
       // `- key: value` opens a mapping whose remaining keys sit two columns in.
       const itemIndent = indent + 2;
       const synthetic = new Line(itemIndent, rest, l.no);
-      synthetic.raw = " ".repeat(itemIndent) + rest;
+      synthetic.src = l.src;
       const sub = [synthetic];
       let j = i + 1;
       while (j < ls.length && ls[j].indent >= itemIndent) sub.push(ls[j++]);
@@ -229,8 +292,8 @@ function parseSeq(ls, i, indent) {
       i = j;
       continue;
     }
-    if (/^[|>][-+]?$/.test(rest)) {
-      const r = blockScalar(rest, ls, i + 1, indent, l.no);
+    if (/^[|>][-+1-9]*$/.test(rest)) {
+      const r = blockScalar(rest, ls, i + 1, indent, l.no, l.src);
       out.push(r.value);
       i = r.next;
       continue;
@@ -248,30 +311,30 @@ function parseMap(ls, i, indent) {
     const l = ls[i];
     const kv = splitKey(l.text, l.no);
     if (!kv) fail(l.no, `expected a key, got: ${l.text}`);
-    if (kv.key in out) fail(l.no, `duplicate key ${kv.key}`);
+    if (Object.hasOwn(out, kv.key)) fail(l.no, `duplicate key ${kv.key}`);
     if (kv.rest === "") {
       const nx = ls[i + 1];
       if (nx && nx.indent > indent) {
         const r = parseBlock(ls, i + 1, nx.indent);
-        out[kv.key] = r.value;
+        put(out, kv.key, r.value);
         i = r.next;
       } else if (nx && nx.indent === indent && (nx.text.startsWith("- ") || nx.text === "-")) {
         const r = parseSeq(ls, i + 1, indent);
-        out[kv.key] = r.value;
+        put(out, kv.key, r.value);
         i = r.next;
       } else {
-        out[kv.key] = null;
+        put(out, kv.key, null);
         i++;
       }
       continue;
     }
-    if (/^[|>][-+]?$/.test(kv.rest)) {
-      const r = blockScalar(kv.rest, ls, i + 1, indent, l.no);
-      out[kv.key] = r.value;
+    if (/^[|>][-+1-9]*$/.test(kv.rest)) {
+      const r = blockScalar(kv.rest, ls, i + 1, indent, l.no, l.src);
+      put(out, kv.key, r.value);
       i = r.next;
       continue;
     }
-    out[kv.key] = scalar(kv.rest, l.no);
+    put(out, kv.key, scalar(kv.rest, l.no));
     i++;
   }
   if (i < ls.length && ls[i].indent > indent) fail(ls[i].no, `unexpected indentation (${ls[i].indent} columns)`);
@@ -281,7 +344,7 @@ function parseMap(ls, i, indent) {
 export function parseYaml(text) {
   const ls = lines(text);
   const raws = text.split("\n");
-  for (const l of ls) l.raw = raws[l.no - 1];
+  for (const l of ls) l.src = raws;
   if (ls.length === 0) return null;
   const r = parseBlock(ls, 0, ls[0].indent);
   if (r.next < ls.length) fail(ls[r.next].no, `unexpected content after the document: ${ls[r.next].text}`);
@@ -304,6 +367,18 @@ function scalarOut(v) {
   return v;
 }
 
+// Whether a multi-line string is written as a `|` block. A string whose block would need a header
+// indicator (a leading blank or indented first line, kept trailing newlines) or would carry a `#`,
+// a carriage return or trailing whitespace is written double-quoted instead, which always reads
+// back and reads the same in every YAML tool (HQ-1406: "\na" read back as "a").
+function blockSafe(v) {
+  const body = v.endsWith("\n") ? v.slice(0, -1) : v;
+  if (body.endsWith("\n") || body.includes("\r") || body.includes("#")) return false;
+  const ls = body.split("\n");
+  if (ls[0] === "" || /^\s/.test(ls[0])) return false;
+  return ls.every((l) => !/\s$/.test(l));
+}
+
 function isScalar(v) {
   return v === null || v === undefined || ["string", "number", "boolean"].includes(typeof v);
 }
@@ -330,7 +405,7 @@ function write(v, indent, out) {
     for (const k of keys) {
       const val = v[k];
       const key = scalarOut(k);
-      if (typeof val === "string" && val.includes("\n")) {
+      if (typeof val === "string" && val.includes("\n") && blockSafe(val)) {
         const body = val.replace(/\n$/, "");
         out.push(`${pad}${key}: ${val.endsWith("\n") ? "|" : "|-"}`);
         for (const l of body.split("\n")) out.push(l === "" ? "" : `${pad}  ${l}`);

package/package.json

@@ -1,33 +1,43 @@
 {
   "name": "create-evda",
-  "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.",
+  "version": "0.1.6",
   "type": "module",
+  "description": "The person layer over the substrate: scaffold and operate an EVDA, a directory that knows what it is. Plain files are the truth, the tooling is optional, and there are no runtime dependencies.",
   "bin": {
-    "create-evda": "create-evda.mjs",
-    "evda": "bin/evda.mjs"
+    "create-evda": "./create-evda.mjs",
+    "evda": "./bin/evda.mjs"
   },
   "engines": {
     "node": ">=20"
   },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "lint": "node scripts/dashes-check.mjs && node scripts/build-templates.mjs --check && node scripts/build-kinds.mjs --check",
+    "templates:build": "node scripts/build-templates.mjs",
+    "templates:check": "node scripts/build-templates.mjs --check",
+    "kinds:build": "node scripts/build-kinds.mjs",
+    "kinds:check": "node scripts/build-kinds.mjs --check",
+    "dashes:check": "node scripts/dashes-check.mjs",
+    "vectors:both": "bash scripts/vectors-both.sh",
+    "doctor": "node bin/evda.mjs doctor",
+    "publish:dry": "node scripts/publish.mjs",
+    "publish:live": "node scripts/publish.mjs --publish"
+  },
   "files": [
     "bin",
+    "hooks",
+    "docs",
     "lib",
     "templates",
     "skills",
     "migrations",
+    "presets",
     "create-evda.mjs",
     "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "evda",
-    "personal-record",
-    "agents",
-    "markdown",
-    "mcp"
+    "CHANGELOG.md"
   ],
-  "author": "Mike Veson",
-  "license": "MIT",
-  "homepage": "https://evda.io"
+  "atlas": {
+    "tier": "block",
+    "domain": "neutral"
+  }
 }

package/presets/journal/preset.json

@@ -0,0 +1,19 @@
+{
+  "id": "journal",
+  "title": "Journal",
+  "for": "Someone who mostly wants to write about their days and the people in them, with little structure.",
+  "folders": [
+    { "path": "Journal", "type": "record", "note": "One file per day, named YYYY-MM-DD.md." },
+    { "path": "Captures", "type": "capture", "note": "A thought as it arrived." },
+    { "path": "Work", "type": "ticket", "note": "One file per thing being done, with its status and the day it is planned for." },
+    { "path": "People", "type": "person", "connectors": ["contacts"], "note": "One file per person." },
+    { "path": "Notes", "type": "concept", "note": "Ideas worth keeping past the day." }
+  ],
+  "mapping": {
+    "journal": "Journal",
+    "journal/captures": "Captures",
+    "work": "Work",
+    "collections": "People",
+    "knowledge": "Notes"
+  }
+}

package/presets/projects-and-areas/preset.json

@@ -0,0 +1,34 @@
+{
+  "id": "projects-and-areas",
+  "title": "Projects and areas",
+  "for": "Someone running several projects and parts of life at once, courses included, who captures fast, sorts later, and looks back each week.",
+  "folders": [
+    { "path": "01_Projects", "type": "project", "note": "One folder per project; a finished one stays here with its status." },
+    { "path": "02_Areas", "note": "Parts of life with no end date: one folder per area." },
+    { "path": "02_Areas/Academics", "type": "course", "note": "One folder per course; a course is a collection like any other." },
+    { "path": "02_Areas/Relationships/People", "type": "person", "connectors": ["contacts"], "note": "One file per person." },
+    { "path": "03_Resources", "note": "What is known, each page citing where it came from." },
+    { "path": "03_Resources/Raw", "type": "source", "connectors": ["url"], "note": "Sources as they arrived, unedited." },
+    { "path": "03_Resources/Wiki/Concepts", "type": "concept", "note": "One page per recurring idea, named." },
+    { "path": "03_Resources/Wiki/Syntheses", "type": "concept", "note": "Connections worked out across ideas." },
+    { "path": "03_Resources/Wiki/Sources", "type": "source", "connectors": ["url"], "note": "A summary per source cited often." },
+    { "path": "04_Work", "type": "ticket", "note": "One file per effort, with its status and the day it is planned for; a board can take its place." },
+    { "path": "05_Process", "type": "capture", "note": "Captures waiting to be filed." },
+    { "path": "05_Process/Processed", "type": "capture", "note": "Captures already filed, kept." },
+    { "path": "05_Process/_media", "type": "blob", "note": "Photos and audio a capture carried." },
+    { "path": "06_Metadata/Daily Journal", "type": "record", "note": "One file per day, named YYYY-MM-DD.md." },
+    { "path": "06_Metadata/Weekly Reviews", "type": "concept", "note": "One look back per week." },
+    { "path": "07_Attachments", "type": "blob", "note": "Files notes link to." }
+  ],
+  "mapping": {
+    "journal": "06_Metadata/Daily Journal",
+    "journal/captures": "05_Process",
+    "work": "04_Work",
+    "collections": "01_Projects",
+    "collections/areas": "02_Areas",
+    "collections/attachments": "07_Attachments",
+    "knowledge": "03_Resources",
+    "knowledge/reviews": "06_Metadata/Weekly Reviews"
+  },
+  "routines": ["morning", "weekly"]
+}

package/skills/evda/SKILL.md

@@ -16,6 +16,12 @@ calls no model; you are their own AI, and everything you keep goes through the t
    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.
+4. Call `evda_check_update` once (throttled to once an hour; most sessions read a cached result).
+   Say nothing if it is current or was skipped. If an update is available or the check failed, say
+   the one line it returns, briefly, and hand them the command it names to run in a terminal. The
+   tool only tells: nothing in this server installs an update. It asks the npm registry for a
+   version number and sends nothing from the record, and it is the only tool here that reaches the
+   network at all. `evda check-update` is the same check from a shell, for a session that has one.
 
 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.
@@ -24,6 +30,20 @@ setup for each client. Do not keep the record some other way.
 
 - **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.
+- **Without being asked.** They should never have to say "save this". When a tool result says
+  nothing from this conversation is filed yet, or a Stop hook asks before you finish, that is this
+  rule: file what they said that is worth keeping, then stop. When `evda.json` says
+  `"filing": "asked"`, they chose to file only when they ask; when it says nothing, ask them once.
+- **One section per conversation.** Your first `evda_write` opens it with one line of `context`;
+  later ones go under it.
+- **Entries grow on their own.** When a person, project or place comes up that already has an
+  entry (check with `evda_search`), file their words with `evda_write` naming it, and if this session
+  can edit files, add a dated section (`## YYYY-MM-DD`) to that entry too; over the tools alone, the
+  daily file is where it lands and `evda organize` proposes its place. One with no entry is offered
+  in one line, never created without their yes. A noted entry is never added to.
+- **The day's entry is their words plus one line of context**: pass `context` to `evda_write`, one
+  line in your words on what the conversation was about. It is written labeled as not theirs; never
+  put your words in `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
@@ -31,6 +51,16 @@ setup for each client. Do not keep the record some other way.
 - **Never write a password, key or token.** The tools refuse one; tell them to keep it in their
   password manager.
 
+## Skills and records inside this one
+
+- **When a process repeats** (the same steps done or explained twice, the same correction twice),
+  write it once with `evda_write_skill`: a kebab-case name, a description saying when to use it, the
+  steps. Tell them in one line. A tool result that says steps ran twice is that moment. Follow the
+  skills `evda_skills` lists; revise one (`revise: true`, `why`) when a run of it goes wrong. Never a
+  rule about their life: no threshold, count or streak about a person.
+- **When they ask for an EVÐA inside this one**, make it with `evda_create_subrecord` and tell them
+  what doctor said. Only pass `bounded: true` with `confirmed: true` after their yes to it.
+
 ## How to talk
 
 - **Never quiz them.** No lists of questions, no check-ins about open items, no "how did X go"
@@ -38,6 +68,16 @@ setup for each client. Do not keep the record some other way.
 - 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.
 
+## Who reads what
+
+- **"Just note this" goes to `evda_note`, not `evda_write`.** No AI reads a noted entry, you
+  included, until they say it can; then confirm which one and call `evda_release_note`.
+- **When a tool says something was not shown** (a noted entry, or a part set to be read by a
+  different AI), tell them in one plain sentence what is there and how they open it. Never guess
+  at what it says.
+- **When they ask which AI is safest,** answer from "What each AI company says" in their README,
+  with its date. Never rank companies by how likely they are to misuse data.
+
 ## Circles
 
 - Everything is private by default.
@@ -46,6 +86,42 @@ setup for each client. Do not keep the record some other way.
 - **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.
 
+## How the record is organized
+
+Organization comes from the preset library, never from you making one up.
+
+- **During setup**, or when they ask how to organize their EVÐA: list the presets with
+  `evda_presets`, say in one line which fits what they told you and why, show the plan with
+  `evda_propose_structure`, and wait for their yes. Only then call `evda_apply_preset` with
+  `confirmed: true`. A yes to something else is not a yes to this.
+- **Later, only when a new kind of thing keeps appearing** (courses, readings, the same kind of
+  note again and again) and a folder in a preset already covers it: name that folder from the
+  library, show it with `evda_propose_structure`, and wait. Never invent a folder the library does
+  not have.
+- **Applying only adds.** It never moves, renames or deletes, and a folder that is already set up
+  differently is reported and left alone. Tell them what it reported.
+- **Where something shared goes:** a plain folder when it is theirs and private; a circle when it
+  is theirs and shared with specific people; its own EVÐA when someone else holds it or it will
+  outlive their involvement (a company, a team's project).
+
+## Gathering a pile they already have
+
+When they point you at something they already keep (a Documents folder, a Notes or Obsidian
+export, a contacts export), call `evda_gather` with those paths. It writes a proposal outside the
+pile and outside the record and changes nothing in either. Tell them in a few lines what it found:
+the preset it fits, the folders it needs, what it kept as references, and what it left for them.
+
+Then take `evda_gather_questions` one at a time, in your own words, in the flow of the
+conversation. Each one changes where something goes; nothing else is ever asked, so never add a
+question of your own and never read them the list. Record each answer with `evda_gather_answer`,
+as they gave it, and say what it moved. Nothing is moved into the record in this step.
+
+When every question is answered, show them the summary once more and ask whether to apply it.
+Only on their yes call `evda_gather_apply` with `confirmed: true` (copying unless they asked to
+move). Tell them what it placed, what it left for them, and the reversal manifest it names:
+`evda gather revert <manifest>` undoes it. When they bring a second pile later, call
+`evda_gather` with `into` set to their record, so only what is new is asked about and placed.
+
 ## Organizing (scheduled or asked)
 
 `evda organize` does the mechanical part itself: it copies each capture, verbatim, into the daily