synabun 2.0.10 → 2.2.0

package/neural-interface/lib/skills/export.js

@@ -0,0 +1,203 @@
+// ── What an install writes for one runtime ──
+// The export of a revision for a target is the revision's folder, byte for byte, unless the target would let the
+// skill be started more freely than its author said (public/shared/skills/ss-profiles.js invocationPlan): then the
+// one setting that keeps it as meant is added to the export, and only to the export (the source revision is never
+// rewritten). Each change is listed (`transforms`) and the export has its own digest: what is installed, and what
+// a plan was approved for, is exactly those bytes.
+//   - Claude Code: `disable-model-invocation: true` / `user-invocable: false` in SKILL.md (that key only);
+//   - Codex: `policy.allow_implicit_invocation: false` in agents/openai.yaml (made when there is none; otherwise
+//     that one value is set and every other value, comment and order is kept);
+//   - OpenCode: metadata `opencode/autoinvoke: "false"` in SKILL.md (the metadata key only);
+//   - Antigravity: `disable-slash-command: true` in SKILL.md (that key only) for a skill the person may not start by
+//     name. Antigravity has no setting that keeps its model from starting a skill: an export of an explicit-only
+//     skill for it is refused (L-08-invocation-unrepresentable), never written wider.
+// A Codex export also carries the harness metadata Codex shows in its skill picker (agents/openai.yaml
+// `interface`: display_name, short_description, default_prompt, from the skill's own name and description; the
+// 02-standards-runtimes report, §6.3). A sidecar that is already there keeps every value it has: only the interface
+// keys it lacks are added (`sidecarInterface` transform), and one that cannot be parsed is left as it is, with a
+// warning. Codex 0.164.0 reads those keys back in skills/list (displayName, shortDescription, defaultPrompt).
+
+import * as YAML from 'yaml';
+import { frontmatter } from './frontmatter.js';
+import { folderDigest } from './library.js';
+import { fromEditing, toEditing } from '../../public/shared/skills/ss-doc.js';
+import { CODEX_SIDECAR, getProfile, invocationPlan, readInvocationIntent } from '../../public/shared/skills/ss-profiles.js';
+
+const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** The Codex picker's words for a skill, from its frontmatter: `{ display_name, short_description, default_prompt }`. */
+export function codexInterfaceFor(data) {
+  const name = String(data?.name || '').trim();
+  const description = String(data?.description || '').replace(/\s+/g, ' ').trim();
+  const display = name.split(/[-_\s]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ').slice(0, 64).trim();
+  const short = clip(description.split(/(?<=[.!?])\s/)[0] || description, 64);
+  const first = description.split(/(?<=[.!?])\s/)[0] || '';
+  const lead = first ? first[0].toLowerCase() + first.slice(1) : '';
+  const prompt = name ? clip(`Use $${name}${lead ? `: ${lead}` : ''}`, 1024) : '';
+  const out = {};
+  if (display) out.display_name = display;
+  if (short) out.short_description = short;
+  if (prompt) out.default_prompt = prompt;
+  return out;
+}
+
+/** A text cut at a word boundary to `max` characters, with an ellipsis when it was cut. */
+function clip(text, max) {
+  const s = String(text || '').trim();
+  if (s.length <= max) return s;
+  const cut = s.slice(0, max - 1);
+  const at = cut.lastIndexOf(' ');
+  return `${(at > max / 2 ? cut.slice(0, at) : cut).trim()}…`;
+}
+
+/**
+ * The export's agents/openai.yaml with the interface keys Codex shows, added only where they are missing: the file
+ * made when there is none, every present value kept, nothing else of the file touched. Returns `{ files, dirs,
+ * transform, diagnostic }` (one of the last two set).
+ */
+export function withCodexInterface(files, dirs, data) {
+  const wanted = codexInterfaceFor(data);
+  if (!Object.keys(wanted).length) return { files, dirs, transform: null, diagnostic: null };
+  const sidecar = readSidecar(files);
+  const transform = (keys, created) => ({ file: CODEX_SIDECAR, op: 'sidecar-interface', keys, created, reason: `Gives Codex the words it shows for this skill (${keys.join(', ')}), from its name and description.` });
+  if (!sidecar.present) {
+    const text = YAML.stringify({ interface: wanted });
+    return { files: [...files, { path: CODEX_SIDECAR, bytes: Buffer.from(text, 'utf-8'), executable: false }], dirs: [...new Set([...dirs, 'agents'])], transform: transform(Object.keys(wanted), true), diagnostic: null };
+  }
+  if (sidecar.error) return { files, dirs, transform: null, diagnostic: { ruleId: 'L-09-sidecar-kept', severity: 'warning', message: `${CODEX_SIDECAR} cannot be read (${sidecar.error}): kept as it is; Codex shows the skill without its picker words.`, file: CODEX_SIDECAR, line: null } };
+  const kept = (why) => ({ files, dirs, transform: null, diagnostic: { ruleId: 'L-09-sidecar-kept', severity: 'warning', message: `${CODEX_SIDECAR} ${why}: kept as it is; Codex shows the skill without its picker words.`, file: CODEX_SIDECAR, line: null } });
+  // Valid YAML that is not a map (a scalar, a list), or an `interface` that is not a map (null, a string, a list):
+  // nothing can be added to it without changing what the author wrote.
+  if (sidecar.data !== null && sidecar.data !== undefined && !isMap(sidecar.data)) return kept('is not a YAML map');
+  if (sidecar.data?.interface !== undefined && !isMap(sidecar.data.interface)) return kept('has an "interface" that is not a map');
+  const have = isMap(sidecar.data?.interface) ? sidecar.data.interface : {};
+  const missing = Object.keys(wanted).filter((k) => have[k] === undefined || have[k] === null || have[k] === '');
+  if (!missing.length) return { files, dirs, transform: null, diagnostic: null };
+  let nextText;
+  try {
+    const doc = YAML.parseDocument(sidecar.text);
+    for (const key of missing) doc.setIn(['interface', key], wanted[key]);
+    nextText = doc.toString();
+  } catch (err) { return kept(`could not take the interface keys (${String(err?.message || err).split('\n')[0]})`); }
+  const back = YAML.parse(nextText);
+  const expected = JSON.parse(JSON.stringify(sidecar.data ?? {}));
+  expected.interface = { ...(isMap(expected.interface) ? expected.interface : {}), ...Object.fromEntries(missing.map((k) => [k, wanted[k]])) };
+  if (JSON.stringify(back) !== JSON.stringify(expected)) return { files, dirs, transform: null, diagnostic: { ruleId: 'L-09-sidecar-kept', severity: 'warning', message: `${CODEX_SIDECAR} could not take the interface keys without changing other values: kept as it is.`, file: CODEX_SIDECAR, line: null } };
+  const at = files.findIndex((f) => f.path === CODEX_SIDECAR);
+  const out = files.map((f, i) => (i === at ? { ...f, bytes: Buffer.from(nextText, 'utf-8') } : f));
+  return { files: out, dirs, transform: transform(missing, false), diagnostic: null };
+}
+
+/** agents/openai.yaml as Codex would read it: `{ present, data, error, text }`. */
+export function readSidecar(files) {
+  const file = (files || []).find((f) => f.path === CODEX_SIDECAR);
+  if (!file) return { present: false, data: null, error: null, text: null };
+  const text = file.bytes.toString('utf-8');
+  try {
+    const doc = YAML.parseDocument(text, { uniqueKeys: true, maxAliasCount: 100 });
+    if (doc.errors.length) return { present: true, data: null, error: String(doc.errors[0].message).split('\n')[0], text };
+    return { present: true, data: doc.toJS({ maxAliasCount: 100 }) ?? null, error: null, text };
+  } catch (err) {
+    return { present: true, data: null, error: String(err?.message || err).split('\n')[0], text };
+  }
+}
+
+/** The SKILL.md of a folder as text and parsed frontmatter. */
+export function readHeadOf(files) {
+  const head = (files || []).find((f) => f.path === 'SKILL.md');
+  const text = head ? head.bytes.toString('utf-8') : '';
+  return { head, text, parsed: frontmatter.parse(text) };
+}
+
+function patchHead(text, changes) {
+  const editing = toEditing(text);
+  const result = frontmatter.patch(editing.text, changes);
+  if (!result.ok) return null;
+  return fromEditing(text, result.text);
+}
+
+/**
+ * The files an install of these files writes for one profile.
+ * @param {{ files: {path, bytes, executable}[], dirs: string[] }} folder
+ * @param {string} profileId
+ * @returns {{ files, dirs, digest: string, transforms: object[], diagnostics: object[], intent: object }}
+ */
+export function buildExport({ files, dirs = [] }, profileId) {
+  const profile = getProfile(profileId);
+  const { text, parsed } = readHeadOf(files);
+  const sidecar = readSidecar(files);
+  const intent = readInvocationIntent({ data: parsed.data, sidecar });
+  const plan = invocationPlan(profileId, { intent, data: parsed.data || {}, sidecar });
+  const out = files.map((f) => ({ ...f }));
+  const outDirs = new Set(dirs);
+  const applied = [];
+  const diagnostics = [...plan.diagnostics];
+  let headText = text;
+  for (const t of plan.transforms) {
+    if (t.op === 'frontmatter' || t.op === 'metadata') {
+      let changes;
+      if (t.op === 'frontmatter') changes = { [t.key]: t.value };
+      else {
+        const current = isMap(parsed.data?.metadata) ? parsed.data.metadata : {};
+        changes = { metadata: { ...current, [t.key]: t.value } };
+      }
+      const next = patchHead(headText, changes);
+      if (next === null) {
+        diagnostics.push({ ruleId: 'L-08-adapt-failed', severity: 'error', message: `The SKILL.md frontmatter could not be changed to keep ${profile?.title || profileId} from ${t.key === 'user-invocable' || t.key === 'disable-slash-command' ? 'showing it to the person' : 'starting it on its own'}: fix the YAML first.`, file: 'SKILL.md', line: null });
+        continue;
+      }
+      headText = next;
+      applied.push(t);
+    } else if (t.op === 'sidecar') {
+      if (!sidecar.present) {
+        out.push({ path: CODEX_SIDECAR, bytes: Buffer.from('policy:\n  allow_implicit_invocation: false\n', 'utf-8'), executable: false });
+        outDirs.add('agents');
+        applied.push({ ...t, created: true });
+        continue;
+      }
+      if (sidecar.error) {
+        diagnostics.push({ ruleId: 'L-08-adapt-failed', severity: 'error', message: `${CODEX_SIDECAR} cannot be read (${sidecar.error}): Codex could start the skill on its own. Fix the file first.`, file: CODEX_SIDECAR, line: null });
+        continue;
+      }
+      let nextText;
+      try {
+        const doc = YAML.parseDocument(sidecar.text);
+        if (!isMap(sidecar.data)) throw new Error('not a YAML map');
+        doc.setIn(t.path, t.value);
+        nextText = doc.toString();
+      } catch (err) {
+        diagnostics.push({ ruleId: 'L-08-adapt-failed', severity: 'error', message: `${CODEX_SIDECAR} could not take policy.allow_implicit_invocation (${String(err?.message || err).split('\n')[0]}): set it yourself.`, file: CODEX_SIDECAR, line: null });
+        continue;
+      }
+      // Read back: the one value changed, nothing else.
+      const back = YAML.parse(nextText);
+      const expected = JSON.parse(JSON.stringify(sidecar.data ?? {}));
+      let node = expected;
+      for (const key of t.path.slice(0, -1)) { if (!isMap(node[key])) node[key] = {}; node = node[key]; }
+      node[t.path[t.path.length - 1]] = t.value;
+      if (JSON.stringify(back) !== JSON.stringify(expected)) {
+        diagnostics.push({ ruleId: 'L-08-adapt-failed', severity: 'error', message: `${CODEX_SIDECAR} could not be changed without changing other values: set policy.allow_implicit_invocation yourself.`, file: CODEX_SIDECAR, line: null });
+        continue;
+      }
+      const at = out.findIndex((f) => f.path === CODEX_SIDECAR);
+      out[at] = { ...out[at], bytes: Buffer.from(nextText, 'utf-8') };
+      applied.push(t);
+    }
+  }
+  if (headText !== text) {
+    const at = out.findIndex((f) => f.path === 'SKILL.md');
+    out[at] = { ...out[at], bytes: Buffer.from(headText, 'utf-8') };
+  }
+  for (const t of applied) diagnostics.push({ ruleId: 'L-08-invocation-adapted', severity: 'info', message: `${t.file}: ${t.reason}`, file: t.file, line: null });
+  // Codex: the words its picker shows, in agents/openai.yaml (added where missing, never over what is there).
+  let withDirs = [...outDirs];
+  let withFiles = out;
+  if (profile?.runtime === 'codex') {
+    const added = withCodexInterface(out, withDirs, parsed.data || {});
+    withFiles = added.files; withDirs = added.dirs;
+    if (added.transform) { applied.push(added.transform); diagnostics.push({ ruleId: 'L-09-sidecar-interface', severity: 'info', message: `${CODEX_SIDECAR}: ${added.transform.reason}`, file: CODEX_SIDECAR, line: null }); }
+    if (added.diagnostic) diagnostics.push(added.diagnostic);
+  }
+  const result = { files: withFiles.sort((a, b) => (a.path < b.path ? -1 : 1)), dirs: withDirs.sort() };
+  return { ...result, digest: folderDigest(result), transforms: applied, diagnostics, intent };
+}

package/neural-interface/lib/skills/frontmatter.js

@@ -0,0 +1,64 @@
+// ── The frontmatter of skills, commands and agents, on the server ──
+// One reader for everything the server says about a SKILL.md, a command or an agent: the library, an opened
+// artifact, the validation route, imports. It is the page's own module (public/shared/skills/ss-frontmatter.js)
+// over the `yaml` package, so the server and the Studio's form read a file the same way, and the checks are the
+// page's too (ss-lint.js).
+
+import * as YAML from 'yaml';
+import { createFrontmatter } from '../../public/shared/skills/ss-frontmatter.js';
+import { LINT_PROFILE, lintArtifact } from '../../public/shared/skills/ss-lint.js';
+import { fromEditing, toEditing } from '../../public/shared/skills/ss-doc.js';
+
+export const frontmatter = createFrontmatter(YAML);
+
+/** The metadata of a document as plain data ({} when it has none, or when it cannot be read). */
+export function frontmatterData(text) {
+  const parsed = frontmatter.parse(text);
+  return { data: parsed.data || Object.create(null), parsed };
+}
+
+/** A value shown as text in a list: the text, or '' for anything that is not text. */
+export const asText = (value) => (typeof value === 'string' ? value : '');
+
+/**
+ * The problems of a document.
+ * @param {{ type: 'skill'|'command'|'agent', text: string, folderName?: string, knownNames?: string[], binary?: boolean }} o
+ *   `binary`: the file is not UTF-8 text (UTF-16, or binary data). Its decoded bytes are not read as metadata:
+ *   that is the one problem, and the Studio shows the file without editing it.
+ */
+export function lintText({ type, text, folderName = '', knownNames = [], binary = false }) {
+  if (binary) {
+    const parsed = frontmatter.parse('');
+    const problem = { ruleId: 'file-not-text', severity: 'error', message: 'This file is not UTF-8 text (UTF-16, or binary data): a runtime may misread it, and it is not edited here. Save it as UTF-8 to edit it.', line: 1 };
+    return { parsed, lint: { profile: LINT_PROFILE, errors: [problem], warnings: [], infos: [], all: [problem] } };
+  }
+  const parsed = frontmatter.parse(text);
+  return { parsed, lint: lintArtifact({ type, parsed, folderName, knownNames }) };
+}
+
+/** What a library row shows of the problems: counts only. */
+export function problemCounts(lint) {
+  return { errors: lint?.errors?.length || 0, warnings: lint?.warnings?.length || 0 };
+}
+
+/**
+ * A SKILL.md given another `name`: that one key changed, every other byte as it was (its line endings and
+ * byte-order mark too). Null when the frontmatter cannot be patched (it does not parse).
+ */
+export function renameSkillDocument(text, name) {
+  const editing = toEditing(text);
+  const result = frontmatter.patch(editing.text, { name });
+  if (!result.ok) return null;
+  return fromEditing(text, result.text);
+}
+
+/**
+ * A SKILL.md with another `description` (the evaluation's optimiser proposes one): that one key changed, every other
+ * byte as it was. Null when the frontmatter cannot be patched.
+ */
+export function withSkillDescription(text, description) {
+  const editing = toEditing(text);
+  const result = frontmatter.patch(editing.text, { description });
+  if (!result.ok) return null;
+  return fromEditing(text, result.text);
+}

package/neural-interface/lib/skills/health.js

@@ -0,0 +1,75 @@
+// Deterministic maintenance on the existing scheduler tick. No model, install, repair or retirement runs here.
+import { localRecord } from './local-store.js';
+import { scanEvidenceKey, scanAllows, SCAN_ENGINE_VERSION, SCAN_POLICY } from './scan.js';
+
+import { buildExport } from './export.js';
+import { TARGET_PROFILE } from '../../public/shared/skills/ss-profiles.js';
+import { folderDigest } from './library.js';
+
+export function createSkillHealth({ dataDir, service, settings, notify = () => false, now = Date.now }) {
+  const store = localRecord(dataDir, 'health', { checkedAt: null, rows: [], notifications: [] });
+  let running = null;
+  const view = () => ({ ...store.read(), enabled: settings().healthEnabled, cadenceHours: settings().cadenceHours, running: !!running, rules: `${SCAN_ENGINE_VERSION}:${SCAN_POLICY}` });
+  async function flush() {
+    const state = store.read();
+    const keep = [];
+    for (const item of state.notifications || []) { try { if (!await notify(item)) keep.push(item); } catch { keep.push(item); } }
+    if (keep.length !== (state.notifications || []).length) { state.notifications = keep; store.write(state); }
+  }
+  async function check({ probe = false } = {}) {
+    if (running) return running;
+    running = (async () => {
+      const previous = store.read();
+      const rows = [];
+      for (const inst of service.deployer.listInstallations({ active: true })) {
+        try {
+          const checked = await service.deployer.verify(inst.installationId, { probeRuntime: probe });
+          let folder = service.library.readRevisionFiles(inst.sourceRevisionId);
+          for (const runtime of inst.destination.affectedRuntimes) folder = buildExport(folder, TARGET_PROFILE[runtime]);
+          const skill = service.library.getSkill(inst.skillId);
+          const scan = service.scanFolder(folder, { name: inst.destination.relativePath, digest: folderDigest(folder), skill });
+          const state = checked.state;
+          const issues = [];
+          if (!state.written) issues.push(state.writtenCheck || 'drift');
+          if (!state.discoverable) issues.push('not_discoverable');
+          if (state.eligibility === 'disabled') issues.push('disabled');
+          if (probe && Object.values(state.discovered || {}).some((v) => v?.discovered === false)) issues.push('not_listed');
+          const acknowledged = inst.scanAcknowledgement?.evidenceKey === scanEvidenceKey(scan) ? inst.scanAcknowledgement.digest : null;
+          if (!scanAllows(scan, { digest: scan.digest, acknowledgedDigest: acknowledged }).ok) issues.push(`scan_${scan.gate === 'allowed' ? 'blocked' : scan.gate}`);
+          const old = previous.rows.find((r) => r.installationId === inst.installationId);
+          const rulesChanged = !!old && (old.scan?.engineVersion !== scan.engineVersion || old.scan?.policy !== scan.policy);
+          rows.push({ installationId: inst.installationId, skillId: inst.skillId, revisionId: inst.sourceRevisionId,
+            name: skill.name, runtime: inst.target.runtime, checkedAt: now(), state, scan, rulesChanged, issues,
+            status: issues.length ? 'attention' : state.eligibility === 'unknown' || !probe || !inst.destination.affectedRuntimes.every((r) => state.discovered?.[r]?.discovered === true) ? 'unverified_runtime' : 'checked',
+            discoveryFresh: probe,
+            // A runtime listing is still not execution or proof of quality.
+            executed: null });
+        } catch (e) {
+          rows.push({ installationId: inst.installationId, skillId: inst.skillId, revisionId: inst.sourceRevisionId,
+            runtime: inst.target.runtime, checkedAt: now(), status: 'error', issues: ['check_error'], error: String(e.code || 'check_failed') });
+        }
+      }
+      const notifications = [...(previous.notifications || [])];
+      for (const row of rows) {
+        const old = previous.rows.find((r) => r.installationId === row.installationId);
+        if ((row.issues.length || row.rulesChanged) && JSON.stringify([old?.issues, old?.scan?.policy, old?.scan?.engineVersion, old?.scan?.findings]) !== JSON.stringify([row.issues, row.scan?.policy, row.scan?.engineVersion, row.scan?.findings])) {
+          notifications.push({ kind: 'skills_health', text: `Skills Studio health: ${row.installationId} (${row.runtime}): ${row.issues.join(', ') || 'scanner rules changed'}. Review Health in Skills Studio. No installed files changed.`, installationId: row.installationId, revisionId: row.revisionId });
+        }
+      }
+      store.write({ checkedAt: now(), rows, notifications: notifications.slice(-100) });
+      service.announce({ type: 'health.changed', attention: rows.filter((r) => r.issues.length).length });
+      await flush();
+      return view();
+    })();
+    try { return await running; } finally { running = null; }
+  }
+  async function tick() {
+    service.telemetry?.prune();
+    if (!settings().healthEnabled) return;
+    await flush();
+    const current = view();
+    if (!current.checkedAt || now() - current.checkedAt >= settings().cadenceHours * 3600000
+      || current.rows.some((r) => r.scan && (r.scan.engineVersion !== SCAN_ENGINE_VERSION || r.scan.policy !== SCAN_POLICY))) await check();
+  }
+  return { view, check, tick };
+}

package/neural-interface/lib/skills/json-edit.js

@@ -0,0 +1,165 @@
+// ── One value of a JSON file, changed in place ──
+// The owner's "Enable for …" (lib/skills/runtime-checks.js enable) changes one value of a runtime's settings file
+// (opencode.json, Claude Code's settings.json) and nothing else: no reformatting, no reordering, every other byte
+// as it was. A small scanner finds where the value at a path sits in the text (and the members of an object, the
+// elements of an array, with their separators); an edit splices the text there. Comments are not JSON: a .jsonc is
+// refused by the caller before this is asked.
+
+/** The nodes of a JSON text with their offsets: `{ type, start, end, value?, members?, elements? }`. */
+export function parseJsonWithOffsets(text) {
+  const s = String(text);
+  let i = 0;
+  const fail = (what) => { throw new SyntaxError(`${what} at ${i}`); };
+  const ws = () => { while (i < s.length && /[ \t\r\n]/.test(s[i])) i++; };
+  const string = () => {
+    const start = i;
+    if (s[i] !== '"') fail('string expected');
+    i++;
+    while (i < s.length && s[i] !== '"') { if (s[i] === '\\') i++; i++; }
+    if (s[i] !== '"') fail('unterminated string');
+    i++;
+    return { type: 'string', start, end: i, value: JSON.parse(s.slice(start, i)) };
+  };
+  const value = () => {
+    ws();
+    const c = s[i];
+    if (c === '{') {
+      const start = i; i++;
+      const members = [];
+      ws();
+      if (s[i] === '}') { i++; return { type: 'object', start, end: i, members }; }
+      for (;;) {
+        ws();
+        const key = string();
+        ws();
+        if (s[i] !== ':') fail(': expected');
+        i++;
+        const v = value();
+        members.push({ key: key.value, keyStart: key.start, valueStart: v.start, valueEnd: v.end, node: v });
+        ws();
+        if (s[i] === ',') { i++; continue; }
+        if (s[i] === '}') { i++; return { type: 'object', start, end: i, members }; }
+        fail(', or } expected');
+      }
+    }
+    if (c === '[') {
+      const start = i; i++;
+      const elements = [];
+      ws();
+      if (s[i] === ']') { i++; return { type: 'array', start, end: i, elements }; }
+      for (;;) {
+        const v = value();
+        elements.push(v);
+        ws();
+        if (s[i] === ',') { i++; continue; }
+        if (s[i] === ']') { i++; return { type: 'array', start, end: i, elements }; }
+        fail(', or ] expected');
+      }
+    }
+    if (c === '"') return string();
+    const start = i;
+    const m = /^(?:true|false|null|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(s.slice(i));
+    if (!m) fail('value expected');
+    i += m[0].length;
+    return { type: 'scalar', start, end: i, value: JSON.parse(m[0]) };
+  };
+  const root = value();
+  ws();
+  if (i !== s.length) fail('trailing text');
+  return root;
+}
+
+/** The node at a path of keys (and array indexes), or null. */
+export function nodeAt(root, path) {
+  let node = root;
+  for (const key of path) {
+    if (!node) return null;
+    if (node.type === 'object') { const m = node.members.find((x) => x.key === key); node = m ? m.node : null; }
+    else if (node.type === 'array' && Number.isInteger(key)) node = node.elements[key] || null;
+    else return null;
+  }
+  return node || null;
+}
+
+/** The text with the value of one existing member replaced by `json` (the JSON text of the new value). */
+export function replaceValue(text, node, json) {
+  return `${text.slice(0, node.start)}${json}${text.slice(node.end)}`;
+}
+
+/**
+ * The text with a member added as the last of an object (the indentation of its last member, or of the object's
+ * closing brace plus two spaces when it is empty); the key must not be there already.
+ */
+export function appendMember(text, objectNode, key, json) {
+  const s = String(text);
+  if (objectNode.type !== 'object') throw new TypeError('not an object');
+  if (objectNode.members.some((m) => m.key === key)) throw new Error(`"${key}" is there already`);
+  const closing = objectNode.end - 1;
+  const last = objectNode.members[objectNode.members.length - 1] || null;
+  if (!last) {
+    const lineStart = s.lastIndexOf('\n', closing) + 1;
+    const inner = lineStart > objectNode.start ? /^[ \t]*/.exec(s.slice(lineStart, closing))[0] : '';
+    const multiline = s.slice(objectNode.start + 1, closing).includes('\n');
+    const pad = multiline ? `\n${inner}  ` : ' ';
+    const tail = multiline ? `\n${inner}` : ' ';
+    return `${s.slice(0, objectNode.start + 1)}${pad}${JSON.stringify(key)}: ${json}${tail}${s.slice(closing)}`;
+  }
+  const lineStart = s.lastIndexOf('\n', last.keyStart) + 1;
+  const sameLine = lineStart <= objectNode.start;
+  const indent = sameLine ? ' ' : `\n${/^[ \t]*/.exec(s.slice(lineStart, last.keyStart))[0]}`;
+  return `${s.slice(0, last.valueEnd)},${indent}${JSON.stringify(key)}: ${json}${s.slice(last.valueEnd)}`;
+}
+
+/** The text without one member of an object (with the separator and the line it stood on). */
+export function removeMember(text, objectNode, key) {
+  const s = String(text);
+  const at = objectNode.members.findIndex((m) => m.key === key);
+  if (at < 0) return s;
+  const m = objectNode.members[at];
+  const prev = objectNode.members[at - 1] || null;
+  const next = objectNode.members[at + 1] || null;
+  let start;
+  let end;
+  if (prev) { start = prev.valueEnd; end = m.valueEnd; }            // ", <key>: <value>" after the one before
+  else if (next) { start = m.keyStart; end = next.keyStart; }        // "<key>: <value>, " before the one after
+  else { start = objectNode.start + 1; end = objectNode.end - 1; }   // the only one: the object is left empty
+  return `${s.slice(0, start)}${s.slice(end)}`;
+}
+
+/** The text without one element of an array (by index). */
+export function removeElement(text, arrayNode, index) {
+  const s = String(text);
+  const e = arrayNode.elements[index];
+  if (!e) return s;
+  const prev = arrayNode.elements[index - 1] || null;
+  const next = arrayNode.elements[index + 1] || null;
+  let start;
+  let end;
+  if (prev) { start = prev.end; end = e.end; }
+  else if (next) { start = e.start; end = next.start; }
+  else { start = arrayNode.start + 1; end = arrayNode.end - 1; }
+  return `${s.slice(0, start)}${s.slice(end)}`;
+}
+
+/**
+ * The text with an element added as the last of an array (on a line of its own, at the indentation of the last
+ * element, when the array spans lines; else after a space).
+ */
+export function appendElement(text, arrayNode, json) {
+  const s = String(text);
+  if (arrayNode.type !== 'array') throw new TypeError('not an array');
+  const closing = arrayNode.end - 1;
+  const last = arrayNode.elements[arrayNode.elements.length - 1] || null;
+  if (!last) {
+    const lineStart = s.lastIndexOf('\n', closing) + 1;
+    const inner = lineStart > arrayNode.start ? /^[ \t]*/.exec(s.slice(lineStart, closing))[0] : '';
+    const multiline = s.slice(arrayNode.start + 1, closing).includes('\n');
+    return multiline
+      ? `${s.slice(0, arrayNode.start + 1)}\n${inner}  ${json}\n${inner}${s.slice(closing)}`
+      : `${s.slice(0, arrayNode.start + 1)}${json}${s.slice(closing)}`;
+  }
+  const lineStart = s.lastIndexOf('\n', last.start) + 1;
+  const sameLine = lineStart <= arrayNode.start;
+  const indent = sameLine ? ' ' : `\n${/^[ \t]*/.exec(s.slice(lineStart, last.start))[0]}`;
+  return `${s.slice(0, last.end)},${indent}${json}${s.slice(last.end)}`;
+}