create-evda 0.1.5 → 0.1.7

package/lib/circle-plan.mjs

@@ -0,0 +1,277 @@
+// Declaring circles over a record that already exists (Spec 08, stage S0).
+//
+// A record adopts circles by saying where its files already are; nothing moves. A plan names each
+// circle by the folders it roots at, most specific first in meaning but in any order on the page:
+//
+//   { "exclude": ["Videos"],
+//     "circles": [
+//       { "name": "therapy",  "roots": ["02_Areas/Health & Energy/Therapy"] },
+//       { "name": "health",   "roots": ["02_Areas/Health & Energy"] },
+//       { "name": "core",     "roots": [""] } ],
+//     "devices": {
+//       "laptop": { "atlasId": "laptop.atlas", "grants": { "*": "owner" } },
+//       "hestia": { "atlasId": "hestia.atlas", "grants": { "core": "editor", "people": "viewer" } } } }
+//
+// A root claims everything under it except another circle's root. So `health` above is every child
+// of Health & Energy except Therapy, written as the direct children the carve-out leaves, found by
+// listing, so its eco.yaml names only paths that exist today. The record root is different
+// (HQ-1364): `core` is written as ONE member, the root itself (`path: ""`), and every other circle
+// carves its subtree out of it by longest member path (`circleForPath`). So a file created at the
+// root tomorrow is core without anyone re-declaring; before this, core enumerated the root's
+// children at declare time and `.doc-actions-ack`, written the next morning, was in no circle.
+//
+// Re-declaring over a record that already has circles keeps each circle's opaque id, release list,
+// rule and table members, mount, policy, description, title and maintainers, and replaces only its
+// path members; the plan is what the paths are, the manifest is everything the owner wrote since.
+//
+// The plan is read from `<circles role>/plan.json` when a command is not handed one (`planBeside`),
+// so doctor and `circles check` exclude what the scan excludes without being told twice.
+//
+// What this module promises, and `evda circles check` proves: every file that syncs is in exactly
+// one circle. A file no circle covers would never reach any device, and one two circles cover would
+// have two access answers.
+
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { excluder, isPlaceholder, walk } from "./sync-rules.mjs";
+import { circleForPath } from "./filechanges.mjs";
+import { circleManifest, readCircles, writeCircle, opaqueIdOf, circlesDir, isRelease } from "./circles.mjs";
+import { grant } from "./grants.mjs";
+import { openEvda, readManifest, writeManifest } from "./manifest.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const PLAN_FILE = "plan.json";
+
+// The plan kept beside the circles it declared, `<circles role>/plan.json`, or null when the record
+// has no circles role or no plan there. Throws when the file is there and is not JSON.
+export function planBeside(evda) {
+  const role = circlesDir(evda);
+  if (!role.mapped || !role.exists || !role.isDir) return null;
+  const p = join(role.abs, PLAN_FILE);
+  if (!existsSync(p)) return null;
+  try {
+    return { path: join(role.rel, PLAN_FILE), abs: p, plan: JSON.parse(readFileSync(p, "utf8")) };
+  } catch (e) {
+    throw new EvdaError(`REFUSED: ${join(role.rel, PLAN_FILE)} is not valid JSON (${e.message}).`, { code: "BAD_PLAN", exit: 2 });
+  }
+}
+
+const norm = (rel) => rel.replace(/^\/+|\/+$/g, "");
+const under = (rel, root) => root === "" || rel === root || rel.startsWith(`${root}/`);
+const strictlyUnder = (rel, root) => rel !== root && under(rel, root);
+
+// Check the plan's own shape. Throws on anything that would make the carve-out ambiguous.
+export function checkPlan(plan) {
+  if (!plan || !Array.isArray(plan.circles) || plan.circles.length === 0) throw new EvdaError("a circle plan needs a non-empty \"circles\" list.", { exit: 2 });
+  const seen = new Map();
+  for (const c of plan.circles) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(c.name ?? "")) throw new EvdaError(`"${c.name}" is not a circle name.`, { exit: 2 });
+    if (!Array.isArray(c.roots) || c.roots.length === 0) throw new EvdaError(`circle "${c.name}" has no roots.`, { exit: 2 });
+    for (const r of c.roots.map(norm)) {
+      if (r.split("/").includes("..")) throw new EvdaError(`circle "${c.name}" root ${r} leaves the record.`, { exit: 2 });
+      if (seen.has(r)) throw new EvdaError(`${r || "(the record root)"} is a root of both "${seen.get(r)}" and "${c.name}".`, { exit: 2 });
+      seen.set(r, c.name);
+    }
+  }
+  return seen;
+}
+
+// The members each circle gets on this disk. Returns { circles: [{ name, public, roots, members:
+// [{ path, isDir }] }], missing: [root] }. A root with nothing on disk is kept as a member, so the
+// declaration still says which circle the path belongs to once it appears.
+export function planCircles(dir, plan, { exclude = excluder(plan.exclude) } = {}) {
+  const rootOf = checkPlan(plan);
+  const roots = [...rootOf.keys()];
+  const missing = [];
+
+  const expand = (rel, circle, out) => {
+    // The record root is one member, never an enumeration (HQ-1364): the other circles carve their
+    // subtrees out of it by longest member path, and a file that appears at the root is its.
+    if (rel === "") {
+      out.push({ path: "", isDir: true });
+      return;
+    }
+    const otherRootBelow = roots.some((r) => rootOf.get(r) !== circle && strictlyUnder(r, rel));
+    const excludedBelow = (plan.exclude ?? []).map(norm).some((x) => strictlyUnder(x, rel));
+    const abs = join(dir, rel);
+    const st = lstatSync(abs);
+    if (!st.isDirectory() || (!otherRootBelow && !excludedBelow)) {
+      out.push({ path: rel, isDir: st.isDirectory() });
+      return;
+    }
+    for (const name of readdirSync(abs).sort()) {
+      const child = rel === "" ? name : `${rel}/${name}`;
+      if (exclude(child)) continue;
+      if (rootOf.has(child) && rootOf.get(child) !== circle) continue;
+      const cst = lstatSync(join(dir, child));
+      // Links and iCloud stubs are never members; the coverage check names them instead.
+      if (cst.isSymbolicLink() || isPlaceholder(name)) continue;
+      expand(child, circle, out);
+    }
+  };
+
+  const circles = plan.circles.map((c) => {
+    const members = [];
+    for (const root of c.roots.map(norm)) {
+      if (!existsSync(root === "" ? dir : join(dir, root))) {
+        missing.push(root);
+        members.push({ path: root, isDir: null });
+        continue;
+      }
+      expand(root, c.name, members);
+    }
+    return { name: c.name, public: c.public === true, roots: c.roots.map(norm), members };
+  });
+  return { circles, missing };
+}
+
+// A plan, as the index `circleForPath` reads, before anything is written.
+export const planIndex = (planned) =>
+  planned.circles.map((c) => ({ name: c.name, id: c.name, public: c.public, members: c.members.map((m) => ({ rel: m.path, isDir: m.isDir })) }));
+
+// Every file under the record, each in exactly one circle. Returns counts and problems; prints
+// nothing. `index` is circleIndex(evda) after S0, or planIndex(plan) before it.
+//
+//   UNCOVERED     a syncable file no circle covers
+//   TWO_CIRCLES   a file two circles cover
+//   SYMLINK       a link inside a circle's tree: never followed, never carried
+//   PLACEHOLDER   an iCloud stub: the bytes are not on this disk
+//   OVERSIZE      larger than the relay's blob lane takes
+//   UNMOUNTED     under the mount root (`mountRoot`, the `mounts` role) and in no circle held from
+//                 another holder (HQ-835)
+export function coverage(dir, index, { exclude, mountRoot = null } = {}) {
+  const perCircle = Object.fromEntries(index.map((c) => [c.name, 0]));
+  const problems = [];
+  let checked = 0;
+  let excluded = 0;
+  for (const e of walk(dir, { exclude })) {
+    if (e.kind === "excluded") { excluded += 1; continue; }
+    let circle = null;
+    try {
+      circle = circleForPath(index, e.rel);
+    } catch (err) {
+      problems.push({ code: "TWO_CIRCLES", rel: e.rel, why: err.message });
+      continue;
+    }
+    if (e.kind === "file") {
+      if (!circle) { problems.push({ code: "UNCOVERED", rel: e.rel, why: "no circle covers it, so it would reach no device" }); continue; }
+      if (mountRoot !== null && e.rel.startsWith(`${mountRoot}/`) && !circle.mount) { problems.push({ code: "UNMOUNTED", rel: e.rel, why: `under the mount root ${mountRoot} and in no circle held from another holder; "${circle.name}" would sync it as this record's own` }); continue; }
+      perCircle[circle.name] += 1;
+      checked += 1;
+      continue;
+    }
+    const why = {
+      symlink: "a symlink: sync never follows or carries one; exclude it in the plan or replace it with the file",
+      placeholder: "an iCloud placeholder: the file's bytes are not on this disk; download it before syncing",
+      oversize: `${e.size} bytes, over the relay's blob lane; exclude it in the plan`,
+    }[e.kind];
+    problems.push({ code: e.kind.toUpperCase(), rel: e.rel, why, circle: circle?.name ?? null });
+  }
+  return { checked, perCircle, excluded, problems };
+}
+
+// Path members named m001, m002, ... in plan order, skipping names `taken` already uses.
+const numbered = (paths, taken = new Set()) => {
+  const out = {};
+  let i = 0;
+  for (const p of paths) {
+    let name;
+    do name = `m${String(++i).padStart(3, "0")}`; while (taken.has(name));
+    out[name] = p;
+  }
+  return out;
+};
+
+// An existing manifest, re-declared: the same object with its path members replaced by the plan's
+// and everything else as the owner left it (id, namespace, title, description, release, mount,
+// policy, maintainers, unknown keys, key order). Rule and table members keep their names and follow
+// the path members. `public` is the plan's, since the plan is what says who may read a circle.
+export function redeclared(was, planned) {
+  if (opaqueIdOf(was) === null) throw new EvdaError(`circle "${planned.name}" is declared with an id this tool cannot keep (${JSON.stringify(was.id)} / ${JSON.stringify(was.namespace)}); it will not mint a new one over it.`, { exit: 2 });
+  const out = { ...was };
+  const kept = Object.entries(was.members ?? {}).filter(([, m]) => m && typeof m === "object" && typeof m.path !== "string");
+  const paths = numbered(planned.members.map((m) => ({ path: m.path })), new Set(kept.map(([n]) => n)));
+  out.members = { ...paths, ...Object.fromEntries(kept) };
+  out.public = planned.public;
+  if (planned.public) {
+    delete out.release;
+    delete out.mount;
+  } else if (out.release === undefined || !isRelease(out.release)) out.release = "never";
+  return out;
+}
+
+// Write the plan into the record: the circles role and grants role in evda.json (added, never
+// replacing a mapping it already has), one eco.yaml per circle, one grant per device per circle.
+// A circle already declared keeps its opaque id and everything the owner wrote on it (`redeclared`).
+// Returns what it wrote.
+export function declare(dir, plan, { circlesRel = "06_Metadata/Circles", grantsRel = "06_Metadata/Grants", recordId, holder, at = new Date() } = {}) {
+  const planned = planCircles(dir, plan);
+  const manifest = readManifest(dir);
+  const layers = Array.isArray(manifest.layers) ? manifest.layers : [];
+  if (!layers.includes("circles")) manifest.layers = [...layers, "circles"];
+  manifest.mapping = { ...(manifest.mapping ?? {}) };
+  manifest.mapping.circles ??= circlesRel;
+  manifest.mapping.grants ??= grantsRel;
+  if (!manifest.id) {
+    if (!recordId) throw new EvdaError("the record has no id; pass recordId (its atlas id) so its grants can say who granted them.", { exit: 2 });
+    manifest.id = recordId;
+  }
+  writeManifest(dir, manifest);
+  mkdirSync(join(dir, manifest.mapping.circles), { recursive: true });
+  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;
+
+  const written = [];
+  for (const c of planned.circles) {
+    const was = existing.get(c.name);
+    const m = was ? redeclared(was, c) : circleManifest({
+      name: c.name,
+      title: c.name,
+      isPublic: c.public,
+      holders: [owner],
+      members: numbered(c.members.map((m) => ({ path: m.path }))),
+      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 }));
+  }
+  const iso = at instanceof Date ? at.toISOString() : String(at);
+  for (const [device, d] of Object.entries(plan.devices ?? {})) {
+    for (const c of planned.circles) {
+      if (c.public) continue;
+      const role = d.grants?.[c.name] ?? d.grants?.["*"];
+      if (!role) continue;
+      written.push(grant(evda, { circle: c.name, to: { id: d.atlasId, kind: "person", name: device }, role, by: manifest.id, at: iso }, { overwrite: true }));
+    }
+  }
+  return { planned, written };
+}
+
+// The circles a device holds and the ones it must never hold, by name.
+//
+// With the record's grant view (`grantView` in filechanges.mjs), the grant files decide: they are
+// what routing, key delivery and receipt already read, so parity reads the same fact rather than a
+// second copy of it. The plan's `devices.<name>.grants` only seeds `declare`. `drift` names each
+// circle where the plan says otherwise, so a stale plan is printed and not believed (HQ-1219,
+// 2026-09-22: Hestia was granted every circle of his record while the plan still said "never
+// therapy"). Without a view the plan decides, as for a record whose grants are not declared yet.
+export function deviceCircles(plan, device, view = null) {
+  const d = plan.devices?.[device];
+  if (!d) throw new EvdaError(`the plan names no device "${device}".`, { exit: 2 });
+  const byPlan = (c) => c.public === true || Boolean(d.grants?.[c.name] || d.grants?.["*"]);
+  let held = byPlan;
+  if (view) {
+    const grantHolds = view.holds(d.atlasId);
+    held = (c) => {
+      if (c.public === true) return true;
+      const entry = view.index.find((e) => e.name === c.name);
+      return entry !== undefined && grantHolds(entry);
+    };
+  }
+  const holds = plan.circles.filter(held).map((c) => c.name);
+  const drift = view
+    ? plan.circles.filter((c) => byPlan(c) !== held(c)).map((c) => `${c.name}: the plan says ${byPlan(c) ? "held" : "never"}, the grant files say ${held(c) ? "held" : "never"}`)
+    : [];
+  return { atlasId: d.atlasId, holds, never: plan.circles.map((c) => c.name).filter((n) => !holds.includes(n)), drift };
+}