@agentshouse/kit 0.0.1 → 0.1.0-alpha.10

package/src/state.js

@@ -0,0 +1,157 @@
+import { chmodSync, renameSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DECLARED_ID, DROPPED_ITEM_NOTES_MAX, SHA256_DIGEST } from "./contract.js";
+import { KitRefusal } from "./refusal.js";
+
+function segment(name) {
+  if (!DECLARED_ID.test(name)) throw new KitRefusal("kit_state_name_invalid", name);
+  return name;
+}
+
+function notePath(directory, instance, service, kind) {
+  return join(directory, "state", segment(instance), kind, `${segment(service)}.json`);
+}
+
+function repositoryPath(directory, key) {
+  if (!/^[a-f0-9]{64}$/.test(key)) throw new KitRefusal("kit_state_name_invalid", key);
+  return join(directory, "state", "repositories", `${key}.json`);
+}
+
+export async function writeText(path, contents, signal, mode = 0o600) {
+  await mkdir(join(path, ".."), { recursive: true, mode: 0o700 });
+  if (signal?.aborted === true) throw new KitRefusal("kit_command_cancelled");
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    await writeFile(temporary, contents, { mode, signal });
+    if (signal?.aborted === true) throw new KitRefusal("kit_command_cancelled");
+    chmodSync(temporary, mode);
+    renameSync(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    if (signal?.aborted === true || error?.name === "AbortError") {
+      throw new KitRefusal("kit_command_cancelled");
+    }
+    throw error;
+  }
+}
+
+export async function writeNote(path, value, signal, mode) {
+  return writeText(path, `${JSON.stringify(value, null, 2)}\n`, signal, mode);
+}
+
+export async function readNote(path, absent) {
+  let stored;
+  try {
+    stored = await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return absent;
+    throw new KitRefusal("kit_state_unreadable", path);
+  }
+  try {
+    return JSON.parse(stored);
+  } catch {
+    throw new KitRefusal("kit_state_unreadable", path);
+  }
+}
+
+export async function readCheckpoint(directory, instance, service) {
+  return readNote(notePath(directory, instance, service, "checkpoints"), null);
+}
+
+export async function writeCheckpoint(directory, instance, service, checkpoint) {
+  return writeNote(notePath(directory, instance, service, "checkpoints"), checkpoint);
+}
+
+export async function readRepositoryState(directory, key) {
+  return readNote(repositoryPath(directory, key), null);
+}
+
+export async function writeRepositoryState(directory, key, state, signal) {
+  return writeNote(repositoryPath(directory, key), state, signal);
+}
+
+function attachmentPath(directory, key) {
+  if (!SHA256_DIGEST.test(key)) throw new KitRefusal("kit_state_name_invalid", key);
+  return join(directory, "state", "attachments", `${key}.json`);
+}
+
+export async function readAttachmentState(directory, key) {
+  return readNote(attachmentPath(directory, key), null);
+}
+
+export async function writeAttachmentState(directory, key, state, signal) {
+  return writeNote(attachmentPath(directory, key), state, signal);
+}
+
+export async function readSourceOriginals(directory, instance, service) {
+  return readNote(notePath(directory, instance, service, "originals"), []);
+}
+
+export async function writeSourceOriginals(directory, instance, service, references, signal) {
+  const path = notePath(directory, instance, service, "originals");
+  if (references.length > 0) return writeNote(path, references, signal);
+  await rm(path, { force: true });
+}
+
+export async function readHealth(directory, instance, service) {
+  return readNote(notePath(directory, instance, service, "health"), null);
+}
+
+export async function recordHealth(directory, instance, service, health) {
+  return writeNote(notePath(directory, instance, service, "health"), health);
+}
+
+export async function readCoverageGaps(directory, instance, service) {
+  return readNote(notePath(directory, instance, service, "gaps"), []);
+}
+
+export async function recordCoverageGaps(directory, instance, service, gaps) {
+  const kept = await readCoverageGaps(directory, instance, service);
+  const merged = kept.filter((note) => !gaps.some((gap) => gap.room === note.room));
+  for (const gap of gaps) {
+    const known = kept.find((note) => note.room === gap.room);
+    merged.push({ ...gap, cursor: known === undefined ? gap.cursor : known.cursor });
+  }
+  await writeNote(notePath(directory, instance, service, "gaps"), merged);
+}
+
+export async function readDroppedItems(directory, instance, service) {
+  return readNote(notePath(directory, instance, service, "dropped"), []);
+}
+
+export async function recordDroppedItems(directory, instance, service, notes) {
+  if (notes.length === 0) return;
+  const kept = [...(await readDroppedItems(directory, instance, service)), ...notes];
+  await writeNote(
+    notePath(directory, instance, service, "dropped"),
+    kept.slice(-DROPPED_ITEM_NOTES_MAX),
+  );
+}
+
+export async function resetCheckpoints(directory, instance, service) {
+  const checkpoints = join(directory, "state", segment(instance), "checkpoints");
+  if (service !== null) {
+    const path = notePath(directory, instance, service, "checkpoints");
+    await rm(notePath(directory, instance, service, "originals"), { force: true });
+    try {
+      await rm(path);
+    } catch (error) {
+      if (error.code === "ENOENT") return [];
+      throw new KitRefusal("kit_state_unreadable", path);
+    }
+    return [service];
+  }
+  let present;
+  try {
+    present = await readdir(checkpoints);
+  } catch {
+    return [];
+  }
+  const reset = present.filter((name) => name.endsWith(".json")).sort();
+  for (const name of reset) {
+    await rm(join(directory, "state", segment(instance), "originals", name), { force: true });
+    await rm(join(checkpoints, name));
+  }
+  return reset.map((name) => name.slice(0, -".json".length));
+}

package/src/sync-library.js

@@ -0,0 +1,293 @@
+import { apply, parse, serialize, VERSION } from "@agentshouse/mdmodel";
+import { KitRefusal } from "./refusal.js";
+
+export { VERSION };
+
+function covers(path, prefix) {
+  const normalized = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  return path === normalized || path.startsWith(`${normalized}/`);
+}
+
+export function relativeTo(authorityPath, housePath) {
+  if (housePath === authorityPath) return "";
+  const prefix = `${authorityPath}/`;
+  if (!housePath.startsWith(prefix)) throw new KitRefusal("kit_sync_path_invalid", housePath);
+  return housePath.slice(prefix.length);
+}
+
+export function housePath(authorityPath, relative) {
+  if (relative === "") return authorityPath;
+  return `${authorityPath}/${relative}`;
+}
+
+export function authorityFor(state, path) {
+  return state.authorities.find((entry) => path === entry.path || path.startsWith(`${entry.path}/`));
+}
+
+export function insideSelection(state, path) {
+  const prefixes = Array.isArray(state.prefixes) ? state.prefixes : [];
+  if (prefixes.some((prefix) => covers(path, prefix))) return true;
+  const authority = authorityFor(state, path);
+  if (authority === undefined) return false;
+  if (relativeTo(authority.path, path) !== "ROOM.md") return false;
+  return prefixes.some(
+    (prefix) => prefix === authority.path || prefix.startsWith(`${authority.path}/`),
+  );
+}
+
+export const OPERATIONS = ["read", "sync", "write", "delete"];
+
+export function admitsOperation(relative, authority, operation) {
+  return authority.operations[operation].some(
+    (scope) => scope === "" || covers(relative, scope.replace(/^\//, "")),
+  );
+}
+
+export function isProtected(relative, authority) {
+  return authority.protected_paths.some((prefix) => {
+    const trimmed = prefix.startsWith(authority.path)
+      ? prefix.slice(authority.path.length).replace(/^\//, "")
+      : prefix.replace(/^\//, "");
+    return trimmed !== "" && covers(relative, trimmed);
+  });
+}
+
+export function isGeneratedProvenance(relative) {
+  return relative.split("/").includes("_provenance");
+}
+
+export function isAuthored(relative, authority) {
+  if (isProtected(relative, authority)) return false;
+  if (isGeneratedProvenance(relative)) return false;
+  return relative === "ROOM.md" || relative.startsWith("library/");
+}
+
+export function isWritable(relative, authority) {
+  return isAuthored(relative, authority) && admitsOperation(relative, authority, "write");
+}
+
+export function unknownPathRefusal(path) {
+  const refusal = new KitRefusal("protected_path", path);
+  refusal.payload = { error: { code: "protected_path", path } };
+  return refusal;
+}
+
+export function protectedPathRefusal(authority, relative) {
+  return unknownPathRefusal(housePath(authority.path, relative));
+}
+
+export function operationDeniedRefusal(authority, relative, operation) {
+  const path = housePath(authority.path, relative);
+  const refusal = new KitRefusal("operation_denied", path);
+  refusal.payload = { error: { code: "operation_denied", path, operation } };
+  return refusal;
+}
+
+export function assertAdmitted(authority, relative, operation) {
+  if (!isAuthored(relative, authority)) throw protectedPathRefusal(authority, relative);
+  if (!admitsOperation(relative, authority, operation)) {
+    throw operationDeniedRefusal(authority, relative, operation);
+  }
+}
+
+export function sidecarPath(path) {
+  const segments = path.split("/");
+  segments.splice(-1, 0, "_provenance");
+  return segments.join("/");
+}
+
+function recordedMap(authority) {
+  return new Map(authority.files.map((file) => [file.path, file]));
+}
+
+function structuredOrReplace(root, relative, recorded, content) {
+  const path = housePath(root, relative);
+  const before = parse(recorded.content, relative);
+  const after = parse(content, relative);
+  if (!before.ok || !after.ok) {
+    return [{ op: "replace", path, base: recorded.revision, content }];
+  }
+  const ops = [];
+  if (before.document.preamble !== after.document.preamble) {
+    ops.push({
+      op: "replace_preamble",
+      path,
+      base: before.document.preamble,
+      content: after.document.preamble,
+    });
+  }
+  const fields = new Set([
+    ...Object.keys(before.document.fields),
+    ...Object.keys(after.document.fields),
+  ]);
+  for (const name of fields) {
+    if (JSON.stringify(before.document.fields[name]) === JSON.stringify(after.document.fields[name])) {
+      continue;
+    }
+    if (after.document.fields[name] === undefined) {
+      return [{ op: "replace", path, base: recorded.revision, content }];
+    }
+    const change = { op: "set_field", path, field: name, value: after.document.fields[name] };
+    if (before.document.fields[name] !== undefined) change.base = before.document.fields[name];
+    ops.push(change);
+  }
+  const sections = new Set([
+    ...Object.keys(before.document.sections),
+    ...Object.keys(after.document.sections),
+  ]);
+  for (const name of sections) {
+    const prior = before.document.sections[name];
+    const next = after.document.sections[name];
+    if (prior === next) continue;
+    if (prior === undefined || next === undefined) {
+      return [{ op: "replace", path, base: recorded.revision, content }];
+    }
+    ops.push({ op: "replace_section", path, section: name, base: prior, content: next });
+  }
+  return ops.length === 0 ? [{ op: "replace", path, base: recorded.revision, content }] : ops;
+}
+
+export function deriveChanges(state, authority, localFiles) {
+  const recorded = recordedMap(authority);
+  const changes = [];
+  for (const [path, content] of Object.entries(localFiles)) {
+    const held = recorded.get(path);
+    if (!isWritable(path, authority)) {
+      if (held !== undefined && held.content === content) continue;
+      if (!insideSelection(state, housePath(authority.path, path))) {
+        throw protectedPathRefusal(authority, path);
+      }
+      assertAdmitted(authority, path, "write");
+    }
+    if (held === undefined) {
+      changes.push({ op: "create", path: housePath(authority.path, path), content });
+      continue;
+    }
+    if (held.content === content) continue;
+    changes.push(...structuredOrReplace(authority.path, path, held, content));
+  }
+  return changes;
+}
+
+function typedContent(change, relative) {
+  const sections = change.sections ?? {};
+  const fields = change.fields ?? {};
+  const parsed = parse(
+    `---\ntype: ${JSON.stringify(change.type)}\n---\n${Object.keys(sections)
+      .map((name) => `## ${name}\n`)
+      .join("")}`,
+    relative,
+  );
+  if (!parsed.ok) return undefined;
+  let document = parsed.document;
+  for (const [name, value] of Object.entries(fields)) {
+    const result = apply(document, { kind: "field", name, value, prior: undefined });
+    if (result.outcome !== "applied") return undefined;
+    document = result.document;
+  }
+  for (const [name, value] of Object.entries(sections)) {
+    const result = apply(document, { kind: "section", name, value, prior: "" });
+    if (result.outcome !== "applied") return undefined;
+    document = result.document;
+  }
+  return serialize(document);
+}
+
+function patchedContent(content, find, replace) {
+  if (typeof content !== "string" || typeof find !== "string" || find.length === 0) return undefined;
+  let count = 0;
+  let index = content.indexOf(find);
+  while (index !== -1) {
+    count += 1;
+    index = content.indexOf(find, index + find.length);
+  }
+  if (count !== 1) return undefined;
+  const at = content.indexOf(find);
+  return `${content.slice(0, at)}${replace}${content.slice(at + find.length)}`;
+}
+
+function applyRename(files, from, to) {
+  const directory = typeof files[from] !== "string";
+  const moved = Object.entries(files).filter(([path]) =>
+    directory ? path.startsWith(`${from}/`) : path === from,
+  );
+  for (const [path] of moved) delete files[path];
+  for (const [path, content] of moved) files[`${to}${path.slice(from.length)}`] = content;
+}
+
+export function applyChanges(files, changes, authorityPath) {
+  const next = { ...files };
+  for (const change of changes) {
+    const relative = relativeTo(authorityPath, change.path);
+    if (change.op === "create") {
+      next[relative] = change.content;
+      continue;
+    }
+    if (change.op === "replace") {
+      next[relative] = change.content;
+      continue;
+    }
+    if (change.op === "remove") {
+      delete next[relative];
+      continue;
+    }
+    if (change.op === "rename") {
+      applyRename(next, relative, relativeTo(authorityPath, change.to));
+      continue;
+    }
+    if (change.op === "create_typed") {
+      const content = typedContent(change, relative);
+      if (content !== undefined) next[relative] = content;
+      continue;
+    }
+    if (change.op === "patch") {
+      const content = patchedContent(next[relative], change.find, change.replace);
+      if (content !== undefined) next[relative] = content;
+      continue;
+    }
+    if (change.op !== "set_field" && change.op !== "replace_section" && change.op !== "replace_preamble") {
+      continue;
+    }
+    const current = next[relative];
+    if (typeof current !== "string") continue;
+    const parsed = parse(current, relative);
+    if (!parsed.ok) continue;
+    const structured =
+      change.op === "set_field"
+        ? { kind: "field", name: change.field, value: change.value, prior: change.base }
+        : change.op === "replace_preamble"
+          ? { kind: "preamble", value: change.content, prior: change.base }
+          : { kind: "section", name: change.section, value: change.content, prior: change.base };
+    const result = apply(parsed.document, structured);
+    if (result.outcome === "applied") next[relative] = serialize(result.document);
+  }
+  return next;
+}
+
+export function resultingFiles(authority, changes) {
+  const files = {};
+  for (const file of authority.files) files[file.path] = file.content;
+  return applyChanges(files, changes, authority.path);
+}
+
+function namedPaths(change) {
+  if (change.op !== "rename") return [change.path];
+  const locations = [change.path, change.to];
+  if (change.base === null || typeof change.base !== "object") return locations;
+  const members = Object.keys(change.base).flatMap((member) =>
+    locations.map((location) => `${location}/${member}`),
+  );
+  return [...locations, ...members];
+}
+
+export function assertWritableChanges(state, changes) {
+  for (const change of changes) {
+    const operation = change.op === "remove" ? "delete" : "write";
+    for (const path of namedPaths(change)) {
+      const authority = authorityFor(state, path);
+      if (authority === undefined) throw unknownPathRefusal(path);
+      if (!insideSelection(state, path)) throw unknownPathRefusal(path);
+      assertAdmitted(authority, relativeTo(authority.path, path), operation);
+    }
+  }
+}

package/src/sync-state.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, realpath, rm } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { EXPLICIT_SYNC_VERSION } from "./contract.js";
+import { KitRefusal } from "./refusal.js";
+import { readNote, writeNote, writeText } from "./state.js";
+import { OPERATIONS } from "./sync-library.js";
+
+export { EXPLICIT_SYNC_VERSION };
+
+export function replicaKey(canonical) {
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+export async function canonicalReplica(replica) {
+  await mkdir(replica, { recursive: true, mode: 0o755 });
+  return realpath(replica);
+}
+
+function syncFile(directory, key, kind = "") {
+  if (!/^[a-f0-9]{64}$/.test(key)) throw new KitRefusal("kit_state_name_invalid", key);
+  const name = kind === "" ? `${key}.json` : `${key}.${kind}.json`;
+  return join(directory, "state", "sync", name);
+}
+
+function recordedAuthority(authority) {
+  const operations = authority?.operations;
+  return (
+    authority?.kind === "room" &&
+    typeof authority.authority === "string" &&
+    typeof authority.path === "string" &&
+    typeof authority?.log_epoch === "string" &&
+    operations !== null &&
+    typeof operations === "object" &&
+    OPERATIONS.every((operation) => Array.isArray(operations[operation]))
+  );
+}
+
+export async function readReplicaState(directory, replica) {
+  let canonical;
+  try {
+    canonical = await realpath(replica);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  const state = await readNote(syncFile(directory, replicaKey(canonical)), null);
+  if (state === null) return null;
+  if (state.version !== EXPLICIT_SYNC_VERSION) return null;
+  if (!Array.isArray(state.authorities) || !state.authorities.every(recordedAuthority)) return null;
+  return state;
+}
+
+export async function writeReplicaState(directory, state, signal) {
+  return writeNote(syncFile(directory, replicaKey(state.directory)), state, signal);
+}
+
+export async function readPending(directory, canonical) {
+  return readNote(syncFile(directory, replicaKey(canonical), "pending"), null);
+}
+
+export async function writePending(directory, canonical, pending, signal) {
+  return writeNote(syncFile(directory, replicaKey(canonical), "pending"), pending, signal);
+}
+
+export async function clearPending(directory, canonical) {
+  const path = syncFile(directory, replicaKey(canonical), "pending");
+  try {
+    await rm(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw new KitRefusal("kit_state_unreadable", path);
+  }
+}
+
+export function locate(replica, rootPath, relative = "") {
+  const base = join(replica, rootPath.replace(/^\//, ""));
+  const target = resolve(base, relative);
+  if (target !== base && !target.startsWith(`${base}/`)) {
+    throw new KitRefusal("kit_sync_path_invalid", relative);
+  }
+  return target;
+}
+
+export async function writeReplicaFile(path, content, signal) {
+  return writeText(path, content, signal, 0o644);
+}
+
+export async function removeReplicaFile(path) {
+  try {
+    await rm(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw new KitRefusal("kit_state_unreadable", path);
+  }
+}
+
+export async function listFiles(root) {
+  let entries;
+  try {
+    entries = await readdir(root, { recursive: true, withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const full = join(entry.parentPath ?? root, entry.name);
+    files.push(relative(root, full).split("\\").join("/"));
+  }
+  return files.sort();
+}
+
+export async function readLocalMap(replica, authorityPath) {
+  const root = locate(replica, authorityPath);
+  const files = {};
+  for (const path of await listFiles(root)) {
+    files[path] = await readFile(join(root, path), "utf8");
+  }
+  return files;
+}