create-evda 0.1.7 → 0.1.8

package/lib/circle-plan.mjs

@@ -39,6 +39,7 @@ import { circleManifest, readCircles, writeCircle, opaqueIdOf, circlesDir, isRel
 import { grant } from "./grants.mjs";
 import { openEvda, readManifest, writeManifest } from "./manifest.mjs";
 import { EvdaError } from "./errors.mjs";
+import { defaultPartsPlan } from "./setup.mjs";
 
 export const PLAN_FILE = "plan.json";
 
@@ -221,7 +222,8 @@ export function declare(dir, plan, { circlesRel = "06_Metadata/Circles", grantsR
   mkdirSync(join(dir, manifest.mapping.grants), { recursive: true });
   const evda = openEvda(dir);
   const existing = new Map((readCircles(evda) ?? []).filter((c) => c.manifest !== null).map((c) => [c.name, c.manifest]));
-  const owner = holder ?? manifest.owner?.name ?? manifest.id;
+  // An owner with no name yet (create-evda run with no --owner) is named by the record id.
+  const owner = holder || manifest.owner?.name || manifest.id;
 
   const written = [];
   for (const c of planned.circles) {
@@ -232,6 +234,8 @@ export function declare(dir, plan, { circlesRel = "06_Metadata/Circles", grantsR
       isPublic: c.public,
       holders: [owner],
       members: numbered(c.members.map((m) => ({ path: m.path }))),
+      // A plan circle may start the circle's rules (Spec 07, section 6); the default parts start empty.
+      policy: plan.circles.find((p) => p.name === c.name)?.policy ?? null,
       description: c.public ? "Public: anyone may read it." : `Private: read by the devices granted it, and no one else.`,
     });
     written.push(writeCircle(evda, c.name, m, { overwrite: true }));
@@ -275,3 +279,22 @@ export function deviceCircles(plan, device, view = null) {
     : [];
   return { atlasId: d.atlasId, holds, never: plan.circles.map((c) => c.name).filter((n) => !holds.includes(n)), drift };
 }
+
+// The default parts (HQ-1925): journal and private, from setup.mjs `defaultPartsPlan`, declared by
+// create-evda on a new record and, on the owner's yes, over an adopted record that has none. A
+// record that already has a private part is left exactly as it is, so a yes can never replace
+// parts the owner declared. `dryRun` answers whether the default is needed and writes nothing.
+// Returns { needed, declared, parts }, parts being the private part names it has or would have.
+export function defaultParts(dir, { dryRun = false, circlesRel = "circles", grantsRel = "grants", at = new Date() } = {}) {
+  const evda = openEvda(dir);
+  const have = (readCircles(evda) ?? []).filter((c) => c.manifest && c.manifest.public !== true && !c.mount).map((c) => c.name).sort();
+  if (have.length) return { needed: false, declared: false, parts: have };
+  const m = evda.manifest;
+  const slug = String(m.name ?? "record").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "record";
+  const recordId = typeof m.id === "string" && m.id ? m.id : `${slug}.atlas`;
+  const plan = defaultPartsPlan(m.mapping ?? {}, recordId);
+  const parts = plan.circles.map((c) => c.name).sort();
+  if (dryRun) return { needed: true, declared: false, parts };
+  declare(dir, plan, { circlesRel, grantsRel, recordId, at });
+  return { needed: false, declared: true, parts };
+}

package/lib/mcp.mjs

@@ -9,9 +9,11 @@
 // stdout carries protocol messages only. Nothing in this file or the tools it calls prints to
 // stdout; doctor's report is captured into the tool result.
 //
-// Every tool here reads and writes files on this machine, with one exception: evda_check_update
-// asks the npm registry for the tooling's latest version number. That is the server's only network
-// call, it carries nothing from the record, and it installs nothing.
+// Every tool here reads and writes files on this machine, with two exceptions. evda_check_update
+// asks the npm registry for the tooling's latest version number; it carries nothing from the record
+// and installs nothing. The device tools (evda_pair_device, evda_sync_devices, HQ-1217) talk to the
+// relay that carries the record between the owner's own devices, and what they send is sealed on
+// this machine: the relay cannot read it.
 
 import { createInterface } from "node:readline";
 import { SCHEMA_VERSION } from "./manifest.mjs";
@@ -28,6 +30,7 @@ import { createSubrecord } from "./subrecord.mjs";
 import { FALSIFY } from "./mcp-auth.mjs";
 import { filingOf, FILING_MODES } from "./day-file.mjs";
 import { readManifest, writeManifest } from "./manifest.mjs";
+import * as pairing from "./pairing.mjs";
 
 // Newest first. The server answers with the client's version when it supports it, and with the
 // newest otherwise; the client decides whether to continue.
@@ -527,10 +530,51 @@ export const TOOLS = [
       return { text: `${r.text}\n\nexit ${r.exit}`, data: { exit: r.exit }, isError: r.exit !== 0 };
     },
   },
+  {
+    name: "evda_pair_device",
+    title: "Pair a phone",
+    description: "Call only when the owner asks to pair, add or connect a phone or another device to their EVÐA. Returns a one-time pairing code and a QR link for the phone, and the steps to do on it. The code works once, for 10 minutes, and the device gets only the parts named (journal by default). Show the code to the owner and no one else.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "What to call the device, such as phone. Default phone." },
+        parts: { type: "array", items: { type: "string" }, description: "The private parts of the record the device may read and add to. Default [\"journal\"]." },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    run: async (evda, args) => {
+      tools.onlyKeys("evda_pair_device", args, ["name", "parts"]);
+      const r = await pairing.pair(evda.dir, { name: args.name, parts: args.parts });
+      return { text: pairing.pairText(r) };
+    },
+  },
+  {
+    name: "evda_sync_devices",
+    title: "Sync with paired devices",
+    description: "Call after the owner used a pairing code on their phone, or when they ask to sync their devices: adds a device that used its code, takes in what paired devices wrote, and sends what changed here. Answers in plain words.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    run: async (evda, args) => {
+      tools.onlyKeys("evda_sync_devices", args, []);
+      return { text: (await pairing.sync(evda.dir)).join("\n") };
+    },
+  },
+  {
+    name: "evda_devices",
+    title: "Paired devices",
+    description: "Lists the devices paired with the owner's EVÐA, whether each is waiting, paired or removed, and which parts each reads. Removing one is a command the owner runs: evda remove <device>.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    run: async (evda, args) => {
+      tools.onlyKeys("evda_devices", args, []);
+      return { text: (await pairing.devices(evda.dir)).join("\n") };
+    },
+  },
   {
     name: "evda_check_update",
     title: "Check for newer EVDA tooling",
-    description: "Asks the npm registry whether a newer version of the EVDA tooling exists, and returns the one line that says so. At most one real check an hour; inside that hour it reports the cached result. A check that fails reports the status as UNKNOWN, never as up to date. This is the only tool that reaches the network, it sends nothing from the record, and it changes nothing: taking the update is a command the owner runs in their own terminal.",
+    description: "Asks the npm registry whether a newer version of the EVDA tooling exists, and returns the one line that says so. At most one real check an hour; inside that hour it reports the cached result. A check that fails reports the status as UNKNOWN, never as up to date. It sends nothing from the record, and it changes nothing: taking the update is a command the owner runs in their own terminal.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
     annotations: { readOnlyHint: true, openWorldHint: true },
     run: async (evda) => {

package/lib/pairing.mjs

@@ -0,0 +1,165 @@
+// Device pairing for the evda CLI and the MCP (HQ-1217): pair a phone, list and remove devices, sync.
+//
+// The pairing code itself is atlas-local's (atlas/block/atlas-local/src/node/pairing.ts), shipped
+// in this package as one bundled file, dist/pairing.mjs (scripts/build-pairing.mjs). It is loaded
+// only when a pairing command runs, because it needs node:sqlite, which the rest of this package
+// does not: an owner on an older Node still has every other command.
+//
+// Everything a person reads from here is plain words. The one credential shown is the pairing code,
+// because typing or scanning it on the phone is the point; no id, key or hash is printed.
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { EvdaError } from "./errors.mjs";
+import { openEvda } from "./manifest.mjs";
+
+const PKG = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const PAIRING_BUNDLE = join(PKG, "dist", "pairing.mjs");
+
+// node:sqlite is unflagged from Node 22.13 (and 23.4); before that it needs --experimental-sqlite.
+export const PAIRING_NODE = "22.13";
+
+/** Why pairing cannot run on this Node, in plain words, or null when it can. */
+export function pairingUnsupported(version = process.versions.node) {
+  const [major, minor] = String(version).split(".").map(Number);
+  const ok = major > 23 || (major === 23 && minor >= 4) || (major === 22 && minor >= 13);
+  return ok ? null : `Pairing a device needs Node ${PAIRING_NODE} or newer, and this is Node ${version}. Everything else in evda works on this Node; install a newer one to pair.`;
+}
+
+let loaded = null;
+
+/** The bundled pairing module, pointed at this package's own lib/. Throws in plain words when it cannot load. */
+export async function loadPairing({ bundle = PAIRING_BUNDLE, version = process.versions.node } = {}) {
+  const unsupported = pairingUnsupported(version);
+  if (unsupported) throw new EvdaError(unsupported, { code: "NODE_TOO_OLD", exit: 2 });
+  if (loaded?.bundle === bundle) return loaded.mod;
+  if (!existsSync(bundle)) {
+    throw new EvdaError("This copy of evda was installed without device pairing. Run it from the published package (npx -p create-evda evda pair), or build it here with `node scripts/build-pairing.mjs`.", { code: "NOT_BUILT", exit: 2 });
+  }
+  // Node 22 and 23 announce node:sqlite as experimental on stderr. That line is for developers, not
+  // for someone pairing a phone, so it is dropped while the bundle loads and nothing else is.
+  const emit = process.emitWarning;
+  process.emitWarning = function (warning, ...rest) {
+    if (/SQLite/i.test(String(warning?.message ?? warning))) return;
+    return emit.call(process, warning, ...rest);
+  };
+  try {
+    const mod = await import(pathToFileURL(bundle).href);
+    mod.usePersonRecord(PKG);
+    loaded = { bundle, mod };
+    return mod;
+  } catch (error) {
+    // A Node that has the version but not the module (started with --no-experimental-sqlite, or a
+    // build without it) fails here, and is told the same thing in the same words.
+    if (error?.code === "ERR_UNKNOWN_BUILTIN_MODULE") {
+      throw new EvdaError(`Pairing a device needs Node ${PAIRING_NODE} or newer with its built-in SQLite, and this Node cannot load it. Everything else in evda works on this Node.`, { code: "NODE_TOO_OLD", exit: 2 });
+    }
+    throw error;
+  } finally {
+    process.emitWarning = emit;
+  }
+}
+
+// A refusal wrote nothing and is exit 2; anything else (the relay unreachable) is exit 1.
+const REFUSALS = /^(Your EVÐA has no private|This record has no private part|There is already a device|There is no paired device|Give the device a name|Name at least one part)/;
+function asEvdaError(error) {
+  if (error instanceof EvdaError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new EvdaError(message, { code: "PAIRING", exit: REFUSALS.test(message) ? 2 : 1 });
+}
+
+/** Where the computer keeps its device state: `<home>/.evda/<record>/`, never inside the record. */
+export function ownerOptions(dir, { env = process.env, relay } = {}) {
+  return { record: dir, home: resolve(env.HOME || homedir()), relayUrl: relay || env.EVDA_RELAY || undefined };
+}
+
+const partsList = (value) => (Array.isArray(value) ? value : String(value ?? "").split(",")).map((s) => String(s).trim()).filter(Boolean);
+
+export async function pair(dir, { name, parts, relay, env } = {}) {
+  const p = await loadPairing();
+  try {
+    return await p.pairDevice(ownerOptions(dir, { env, relay }), { name: name ?? "phone", parts: partsList(parts ?? "journal") });
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+export const NO_DEVICES = "No devices are paired with this EVÐA.";
+
+// The computer's list of devices lives beside its device state (pairing.ts, paired-devices.json).
+// A record with no id, or no list there, has paired nothing: that is answered without loading the
+// bundle, so listing devices on a fresh record, or on a Node or a copy that cannot pair, is an
+// answer and not an error.
+function pairedList(dir, env) {
+  let id;
+  try { id = openEvda(dir).manifest.id; } catch { return null; }
+  if (typeof id !== "string" || !id || /[/\\]/.test(id)) return null;
+  return join(resolve(env.HOME || homedir()), ".evda", id, "paired-devices.json");
+}
+
+export async function devices(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [NO_DEVICES];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.deviceLines(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** The devices as data, for an app (HQ-1925): `[{name, state, parts, since}]`, empty when nothing is paired. No id. */
+export async function deviceData(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.deviceList(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** One sync as data, for an app (HQ-1925): `{paired: [names], received, sent, refused}`. No id. */
+export async function syncData(dir, { relay, env } = {}) {
+  const p = await loadPairing();
+  try {
+    return await p.syncOnce(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+export async function remove(dir, name, { relay, env } = {}) {
+  if (!name || !String(name).trim()) throw new EvdaError("Say which device to remove: evda remove <device>. `evda devices` lists them.", { code: "USAGE", exit: 2 });
+  const p = await loadPairing();
+  try {
+    return await p.removeDeviceWords(ownerOptions(dir, { env, relay }), String(name).trim());
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+export async function sync(dir, { relay, env } = {}) {
+  const p = await loadPairing();
+  try {
+    return await p.syncWords(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** The MCP tool's answer: the code, the QR link, and what to do on the phone, step by step. */
+export function pairText(r) {
+  return [
+    `Pairing code for ${r.name}: ${r.code}`,
+    `QR link (make it a QR code, or open it on the phone): ${r.qr}`,
+    "",
+    "On the phone:",
+    ...r.phoneSteps.map((s, i) => `${i + 1}. ${s}`),
+    "",
+    `${r.name} will be able to read and add to ${r.parts.join(", ")}, and nothing else. The code is a key until it is used: show it only to the owner.`,
+  ].join("\n");
+}

package/lib/setup.mjs

@@ -405,3 +405,44 @@ export async function interview(opts, io, { presets = [] } = {}) {
   }
   return a;
 }
+
+// ─── The parts a record starts with (HQ-1925) ────────────────────────
+//
+// Decided by the owner: privacy is set per folder when the record is made, everything is
+// accessible by default, and the AI reads on request. So a new record is split into two parts on
+// day one, and a phone can be added with no terminal step:
+//   journal  the day files and captures, wherever the manifest maps them
+//   private  the record root: everything else, including any folder made later
+// The computer holds both as owner. A phone is offered the journal and nothing else.
+// Pure, like the rest of this file, so the app's window reads the same words; circle-plan.mjs
+// `defaultParts` writes the plan.
+
+export const JOURNAL_PART = "journal";
+export const PRIVATE_PART = "private";
+/** What Add a phone offers a phone. */
+export const PHONE_PARTS = [JOURNAL_PART];
+/** The roles whose folders are the journal. */
+const JOURNAL_ROLES = ["record/daily", "record/captures"];
+
+/** The circle plan for a record's default parts, from its manifest mapping and its id. */
+export function defaultPartsPlan(mapping = {}, recordId) {
+  const roots = [...new Set(JOURNAL_ROLES.map((r) => mapping[r]).filter((p) => typeof p === "string").map((p) => p.replace(/^\/+|\/+$/g, "")).filter(Boolean))];
+  // Each starts with an empty policy: the owner's corrections about a part land there.
+  const circles = roots.length ? [{ name: JOURNAL_PART, roots, policy: [] }] : [];
+  circles.push({ name: PRIVATE_PART, roots: [""], policy: [] });
+  return { circles, devices: { computer: { atlasId: recordId, grants: { "*": "owner" } } } };
+}
+
+/** One line for create-evda's report. */
+export const PARTS_LINE = "parts: journal (your daily pages and captures) and private (everything else). A phone you add gets the journal.";
+
+/** What the app shows when an adopted record has no parts, and the one button that splits it. */
+export const PARTS_OFFER = {
+  title: "Your EVÐA is not split into parts yet",
+  lines: [
+    "A phone only gets the parts of your EVÐA you give it, so this Mac needs to know which part is your journal.",
+    "This makes two parts. Journal is your daily pages and captures, and it is what a phone gets. Private is everything else, and it stays on this Mac.",
+    "Nothing in your files moves or changes, and nothing reaches a phone until you add one.",
+  ],
+  button: "Split it into journal and private",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-evda",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "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": {
@@ -22,13 +22,15 @@
     "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"
+    "publish:live": "node scripts/publish.mjs --publish",
+    "pairing:build": "node scripts/build-pairing.mjs"
   },
   "files": [
     "bin",
     "hooks",
     "docs",
     "lib",
+    "dist",
     "templates",
     "skills",
     "migrations",

package/skills/evda/SKILL.md

@@ -20,8 +20,7 @@ calls no model; you are their own AI, and everything you keep goes through the t
    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.
+   version number and sends nothing from the record. `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.