codetrellis 0.0.0-stage → 0.3.0

package/src/backend/services/comment-service.js

@@ -0,0 +1,168 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var comment_service_exports = {};
+__export(comment_service_exports, {
+  addComment: () => addComment,
+  deleteComment: () => deleteComment,
+  getComments: () => getComments,
+  listCommentsFlat: () => listCommentsFlat,
+  listCommentsForPlanSince: () => listCommentsForPlanSince,
+  listItemComments: () => listItemComments
+});
+module.exports = __toCommonJS(comment_service_exports);
+var import_node_crypto = require("node:crypto");
+var import_database = require("./database");
+var import_persistence = require("./persistence");
+function inferSource(authorType, explicit) {
+  if (explicit) return explicit;
+  return authorType === "human" || authorType === "unverified" ? "human" : "agent";
+}
+function addComment(targetType, targetUid, author, authorType, body, commentTypeOrOpts = "comment", parentUidLegacy) {
+  const opts = typeof commentTypeOrOpts === "string" ? { commentType: commentTypeOrOpts, parentUid: parentUidLegacy } : commentTypeOrOpts;
+  const uid = (0, import_node_crypto.randomUUID)();
+  const now = Date.now();
+  const commentType = opts.commentType ?? "comment";
+  const kind = opts.kind ?? null;
+  const source = inferSource(authorType, opts.source);
+  const metadataJson = opts.metadata ? JSON.stringify(opts.metadata) : null;
+  (0, import_database.getDb)().run(
+    `INSERT INTO comments (uid, target_type, target_uid, parent_uid, author, author_type, body, comment_type, kind, source, metadata, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [uid, targetType, targetUid, opts.parentUid || null, author, authorType, body, commentType, kind, source, metadataJson, now]
+  );
+  (0, import_persistence.markDirty)();
+  return {
+    uid,
+    targetType,
+    targetUid,
+    parentUid: opts.parentUid || null,
+    author,
+    authorType,
+    body,
+    commentType,
+    kind: kind ?? void 0,
+    source,
+    metadata: opts.metadata,
+    createdAt: now
+  };
+}
+function rowToComment(r) {
+  let metadata;
+  try {
+    metadata = r[10] ? JSON.parse(r[10]) : void 0;
+  } catch {
+    metadata = void 0;
+  }
+  return {
+    uid: r[0],
+    targetType: r[1],
+    targetUid: r[2],
+    parentUid: r[3],
+    author: r[4],
+    authorType: r[5],
+    body: r[6],
+    commentType: r[7],
+    kind: r[8] ?? void 0,
+    source: r[9] ?? void 0,
+    metadata,
+    createdAt: r[11]
+  };
+}
+const COMMENT_COLUMNS = `uid, target_type, target_uid, parent_uid, author, author_type, body, comment_type, kind, source, metadata, created_at`;
+function deleteComment(uid) {
+  const db = (0, import_database.getDb)();
+  const before = db.exec(`SELECT uid FROM comments WHERE uid = ?`, [uid]);
+  if (!before[0]?.values[0]) return false;
+  db.run(`DELETE FROM comments WHERE uid = ?`, [uid]);
+  (0, import_persistence.markDirty)();
+  return true;
+}
+function getComments(targetUid) {
+  const result = (0, import_database.getDb)().exec(
+    `SELECT ${COMMENT_COLUMNS}
+     FROM comments WHERE target_uid = ? ORDER BY created_at ASC`,
+    [targetUid]
+  );
+  if (!result[0]) return [];
+  const all = result[0].values.map((r) => ({
+    ...rowToComment(r),
+    replies: []
+  }));
+  const topLevel = [];
+  const byUid = /* @__PURE__ */ new Map();
+  for (const c of all) {
+    byUid.set(c.uid, c);
+  }
+  for (const c of all) {
+    if (c.parentUid && byUid.has(c.parentUid)) {
+      byUid.get(c.parentUid).replies.push(c);
+    } else {
+      topLevel.push(c);
+    }
+  }
+  return topLevel;
+}
+function listCommentsFlat(targetUid) {
+  const result = (0, import_database.getDb)().exec(
+    `SELECT ${COMMENT_COLUMNS}
+     FROM comments WHERE target_uid = ? ORDER BY created_at ASC`,
+    [targetUid]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map((r) => rowToComment(r));
+}
+function listItemComments(itemUid) {
+  const result = (0, import_database.getDb)().exec(
+    `SELECT ${COMMENT_COLUMNS}
+     FROM comments
+     WHERE target_uid = ? AND target_type IN ('item', 'task')
+     ORDER BY created_at ASC`,
+    [itemUid]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map((r) => rowToComment(r));
+}
+function listCommentsForPlanSince(planUid, since) {
+  const db = (0, import_database.getDb)();
+  const itemRows = db.exec(`SELECT uid FROM plan_items WHERE plan_uid = ?`, [planUid]);
+  let targetUids = (itemRows[0]?.values ?? []).map((r) => r[0]);
+  if (targetUids.length === 0) {
+    const taskRows = db.exec(`SELECT uid FROM tasks WHERE plan_uid = ?`, [planUid]);
+    targetUids = (taskRows[0]?.values ?? []).map((r) => r[0]);
+  }
+  if (targetUids.length === 0) return [];
+  const placeholders = targetUids.map(() => "?").join(", ");
+  const result = db.exec(
+    `SELECT ${COMMENT_COLUMNS}
+     FROM comments
+     WHERE target_uid IN (${placeholders}) AND created_at > ?
+     ORDER BY created_at ASC`,
+    [...targetUids, since]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map((r) => rowToComment(r));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  addComment,
+  deleteComment,
+  getComments,
+  listCommentsFlat,
+  listCommentsForPlanSince,
+  listItemComments
+});

package/src/backend/services/commit-attribution.js

@@ -0,0 +1,134 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var commit_attribution_exports = {};
+__export(commit_attribution_exports, {
+  NO_KNOWLEDGE: () => NO_KNOWLEDGE,
+  agentFromMessage: () => agentFromMessage,
+  attributeCommits: () => attributeCommits,
+  isProjectRelativePath: () => isProjectRelativePath,
+  recordedKnowledge: () => recordedKnowledge
+});
+module.exports = __toCommonJS(commit_attribution_exports);
+var import_node_fs = __toESM(require("node:fs"));
+var import_database = require("./database");
+var import_replay_frames = require("./replay-frames");
+const NO_KNOWLEDGE = { seenBy: () => /* @__PURE__ */ new Map(), sessionAt: () => null, taskOf: () => null };
+const AGENT_NAMES = /\b(claude|codex|copilot|cursor|gemini|aider|devin|windsurf|amp)\b/i;
+function agentFromMessage(body) {
+  const line = body.match(/^agent:\s*(\S+)/m);
+  if (line) return { agent: line[1], how: "commit message", words: `${line[1]}, from the commit message` };
+  for (const m of body.matchAll(/^Co-Authored-By:\s*([^<\n]+?)\s*<[^>\n]*>\s*$/gim)) {
+    const name = m[1].match(AGENT_NAMES);
+    if (name) {
+      const agent = name[1].toLowerCase();
+      return { agent, how: "commit message", words: `${agent}, from the commit's Co-Authored-By trailer (${m[1].trim()})` };
+    }
+  }
+  return null;
+}
+const basename = (p) => p.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? p;
+function attributeCommits(rows, checkoutRoot, know = NO_KNOWLEDGE) {
+  const out = /* @__PURE__ */ new Map();
+  const seen = know.seenBy(rows.map((r) => r.sha));
+  for (const r of rows) {
+    const frame = seen.get(r.sha);
+    const fromMessage = agentFromMessage(r.body);
+    let a = fromMessage ? { ...fromMessage, sessionId: frame?.sessionId ?? null } : null;
+    if (!a && frame?.agentType) {
+      a = {
+        agent: frame.agentType,
+        how: "seen",
+        sessionId: frame.sessionId,
+        words: `${frame.agentType}, seen: it landed while CodeTrellis recorded ${frame.agentType}'s session${frame.workstreamRoot ? ` in ${basename(frame.workstreamRoot)}` : ""}`
+      };
+    }
+    if (!a && checkoutRoot) {
+      const open = know.sessionAt(checkoutRoot, r.at);
+      if (open) {
+        a = {
+          agent: open.agentType,
+          how: "timing",
+          sessionId: open.sessionId,
+          words: `probably ${open.agentType}: committed while ${open.agentType}'s session was open in this checkout`
+        };
+      }
+    }
+    if (!a) continue;
+    if (a.sessionId) {
+      const t = know.taskOf(a.sessionId);
+      if (t) {
+        a.task = t.task;
+        a.plan = t.plan;
+      }
+    }
+    out.set(r.sha, a);
+  }
+  return out;
+}
+const SESSION_GRACE_MS = 10 * 6e4;
+const trim = (p) => p.replace(/[\\/]+$/, "");
+function recordedKnowledge(projectPath) {
+  return {
+    seenBy: (shas) => (0, import_replay_frames.framesByCommit)(projectPath, shas),
+    sessionAt: (checkoutRoot, at) => {
+      const spelled = trim(checkoutRoot);
+      let real = spelled;
+      try {
+        real = import_node_fs.default.realpathSync.native(spelled);
+      } catch {
+      }
+      const row = (0, import_database.getDb)().exec(
+        `SELECT session_id, agent_type FROM agent_sessions
+         WHERE workstream_root IN (?, ?) AND connected_at <= ? AND last_seen + ? >= ?
+         ORDER BY connected_at DESC LIMIT 1`,
+        // A commit's time is whole seconds: one made in the second the session started is in it.
+        [spelled, real, at + 999, SESSION_GRACE_MS, at]
+      )[0]?.values?.[0];
+      return row ? { sessionId: String(row[0]), agentType: String(row[1]) } : null;
+    },
+    taskOf: (sessionId) => {
+      const row = (0, import_database.getDb)().exec(
+        `SELECT i.uid, i.title, p.uid, p.title FROM plan_items i JOIN plans p ON p.uid = i.plan_uid
+         WHERE i.assignee_session = ? ORDER BY i.rowid DESC LIMIT 1`,
+        [sessionId]
+      )[0]?.values?.[0];
+      return row ? { task: { uid: String(row[0]), title: String(row[1]) }, plan: { uid: String(row[2]), title: String(row[3]) } } : null;
+    }
+  };
+}
+function isProjectRelativePath(rel) {
+  return typeof rel === "string" && rel.length > 0 && !rel.startsWith("-") && !rel.startsWith(":") && !rel.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(rel) && !rel.split(/[\\/]/).includes("..");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NO_KNOWLEDGE,
+  agentFromMessage,
+  attributeCommits,
+  isProjectRelativePath,
+  recordedKnowledge
+});

package/src/backend/services/commit-edges.js

@@ -0,0 +1,99 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var commit_edges_exports = {};
+__export(commit_edges_exports, {
+  MAX_PARSED: () => MAX_PARSED,
+  clearCommitEdgeCache: () => clearCommitEdgeCache,
+  commitEdges: () => commitEdges
+});
+module.exports = __toCommonJS(commit_edges_exports);
+var import_node_path = __toESM(require("node:path"));
+const MAX_PARSED = 400;
+const IMPORT_CACHE_MAX = 2e4;
+const importCache = /* @__PURE__ */ new Map();
+function clearCommitEdgeCache() {
+  importCache.clear();
+}
+function commitEdges(input, deps) {
+  const { projectPath, files, oids, live } = input;
+  const liveOut = /* @__PURE__ */ new Map();
+  for (const e of live.edges) {
+    const i = e.indexOf("->");
+    if (i === -1) continue;
+    const src = e.slice(0, i);
+    const list = liveOut.get(src);
+    if (list) list.push(e.slice(i + 2));
+    else liveOut.set(src, [e.slice(i + 2)]);
+  }
+  const edges = /* @__PURE__ */ new Set();
+  const toParse = [];
+  for (const [rel, { hash }] of files) {
+    const same = live.files.get(rel)?.hash === hash;
+    const targets = liveOut.get(rel) ?? [];
+    if (same && targets.every((t) => files.has(t))) {
+      for (const t of targets) edges.add(`${rel}->${t}`);
+    } else {
+      toParse.push(rel);
+    }
+  }
+  if (toParse.length > MAX_PARSED) {
+    return {
+      ok: false,
+      reason: `${toParse.length} files differ from the working tree at this commit, more than the ${MAX_PARSED} parsed to find its dependencies.`
+    };
+  }
+  const uncached = [...new Set(toParse.map((rel) => oids.get(rel)).filter((o) => !!o && !importCache.has(o)))];
+  const blobs = uncached.length ? deps.readBlobs(uncached) : /* @__PURE__ */ new Map();
+  const knownFiles = new Set([...files.keys()].map((rel) => import_node_path.default.join(projectPath, rel)));
+  for (const rel of toParse) {
+    const oid = oids.get(rel);
+    if (!oid) continue;
+    const abs = import_node_path.default.join(projectPath, rel);
+    if (!importCache.has(oid)) {
+      const content = blobs.get(oid);
+      if (content === void 0) continue;
+      if (importCache.size >= IMPORT_CACHE_MAX) importCache.clear();
+      importCache.set(oid, deps.parseImports(abs, content));
+    }
+    const parsed = importCache.get(oid);
+    if (!parsed) continue;
+    for (const imp of parsed.imports) {
+      const target = deps.resolve(parsed.language, imp.source, abs, knownFiles, imp.isRelative);
+      if (!target || target === abs) continue;
+      const targetRel = deps.relative(target);
+      if (files.has(targetRel)) edges.add(`${rel}->${targetRel}`);
+    }
+  }
+  return { ok: true, edges, parsed: toParse.length };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MAX_PARSED,
+  clearCommitEdgeCache,
+  commitEdges
+});

package/src/backend/services/confined-fs.js

@@ -0,0 +1,241 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var confined_fs_exports = {};
+__export(confined_fs_exports, {
+  ConfinementError: () => ConfinementError,
+  canonicalRoot: () => canonicalRoot,
+  isInside: () => isInside,
+  isWithin: () => isWithin,
+  openReadStreamWithin: () => openReadStreamWithin,
+  readFileWithin: () => readFileWithin,
+  readTextWithin: () => readTextWithin,
+  removeWithin: () => removeWithin,
+  resolveWithin: () => resolveWithin,
+  writeFileWithin: () => writeFileWithin
+});
+module.exports = __toCommonJS(confined_fs_exports);
+var fs = __toESM(require("node:fs"));
+var path = __toESM(require("node:path"));
+const HAS_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" && process.platform !== "win32";
+class ConfinementError extends Error {
+  code = "EOUTSIDE_ROOT";
+  constructor(message) {
+    super(message);
+    this.name = "ConfinementError";
+  }
+}
+function canonicalRoot(root) {
+  if (!root || typeof root !== "string") {
+    throw new ConfinementError("A containment root is required");
+  }
+  try {
+    return fs.realpathSync.native(path.resolve(root));
+  } catch (err) {
+    throw new ConfinementError(
+      `Cannot canonicalise the containment root "${root}": ${err.message}`
+    );
+  }
+}
+function resolveWithin(root, candidate, label = "path") {
+  if (typeof candidate !== "string" || candidate.length === 0) {
+    throw new ConfinementError(`${label}: a path is required`);
+  }
+  if (candidate.includes("\0")) {
+    throw new ConfinementError(`${label}: path contains a NUL byte`);
+  }
+  const canonRoot = canonicalRoot(root);
+  const joined = path.resolve(canonRoot, candidate);
+  let existing = joined;
+  const missing = [];
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) break;
+    missing.unshift(path.basename(existing));
+    existing = parent;
+  }
+  assertNoSymlinkOnPath(canonRoot, existing, label);
+  let canonExisting;
+  try {
+    canonExisting = fs.realpathSync.native(existing);
+  } catch (err) {
+    throw new ConfinementError(`${label}: cannot resolve "${candidate}": ${err.message}`);
+  }
+  if (!isInside(canonRoot, canonExisting)) {
+    throw new ConfinementError(
+      `${label}: resolves outside the permitted directory (resolved to ${canonExisting}, which is not inside ${canonRoot})`
+    );
+  }
+  return missing.length ? path.join(canonExisting, ...missing) : canonExisting;
+}
+function isInside(root, target) {
+  if (target === root) return true;
+  const rel = path.relative(root, target);
+  return rel.length > 0 && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+function assertNoSymlinkOnPath(root, target, label) {
+  let current = target;
+  while (current !== root && current.length > root.length) {
+    let st;
+    try {
+      st = fs.lstatSync(current);
+    } catch {
+      return;
+    }
+    if (st.isSymbolicLink()) {
+      throw new ConfinementError(
+        `${label}: "${current}" is a symbolic link. Links are not followed at this boundary.`
+      );
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+function readFileWithin(root, candidate, label = "path") {
+  const target = resolveWithin(root, candidate, label);
+  const flags = HAS_NOFOLLOW ? fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW : fs.constants.O_RDONLY;
+  let fd = null;
+  try {
+    fd = fs.openSync(target, flags);
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) {
+      throw new ConfinementError(`${label}: not a regular file`);
+    }
+    return fs.readFileSync(fd);
+  } catch (err) {
+    if (err instanceof ConfinementError) throw err;
+    const e = err;
+    if (e.code === "ELOOP") {
+      throw new ConfinementError(`${label}: refused to follow a symbolic link`);
+    }
+    throw err;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+      }
+    }
+  }
+}
+function openReadStreamWithin(root, candidate, opts = {}, label = "path") {
+  const target = resolveWithin(root, candidate, label);
+  const flags = HAS_NOFOLLOW ? fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW : fs.constants.O_RDONLY;
+  let fd = null;
+  try {
+    fd = fs.openSync(target, flags);
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) {
+      throw new ConfinementError(`${label}: not a regular file`);
+    }
+    const stream = fs.createReadStream("", { fd, start: opts.start, end: opts.end, autoClose: true });
+    fd = null;
+    return { stream, size: st.size, mtimeMs: st.mtimeMs };
+  } catch (err) {
+    if (err instanceof ConfinementError) throw err;
+    const e = err;
+    if (e.code === "ELOOP") {
+      throw new ConfinementError(`${label}: refused to follow a symbolic link`);
+    }
+    throw err;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+      }
+    }
+  }
+}
+function readTextWithin(root, candidate, label = "path") {
+  return readFileWithin(root, candidate, label).toString("utf-8");
+}
+function writeFileWithin(root, candidate, data, label = "path") {
+  const target = resolveWithin(root, candidate, label);
+  const dir = path.dirname(target);
+  fs.mkdirSync(dir, { recursive: true });
+  const canonDir = resolveWithin(root, dir, `${label} (directory)`);
+  const tmp = path.join(canonDir, `.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  let fd = null;
+  try {
+    fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 384);
+    fs.writeFileSync(fd, data);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    try {
+      const st = fs.lstatSync(target);
+      if (st.isSymbolicLink()) {
+        throw new ConfinementError(`${label}: destination is a symbolic link; refusing to write through it`);
+      }
+    } catch (err) {
+      if (err instanceof ConfinementError) throw err;
+    }
+    fs.renameSync(tmp, target);
+    return target;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+      }
+    }
+    try {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    } catch {
+    }
+  }
+}
+function removeWithin(root, candidate, opts = {}, label = "path") {
+  const target = resolveWithin(root, candidate, label);
+  if (target === canonicalRoot(root)) {
+    throw new ConfinementError(`${label}: refusing to delete the containment root itself`);
+  }
+  fs.rmSync(target, { recursive: opts.recursive === true, force: false });
+}
+function isWithin(root, candidate) {
+  try {
+    resolveWithin(root, candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConfinementError,
+  canonicalRoot,
+  isInside,
+  isWithin,
+  openReadStreamWithin,
+  readFileWithin,
+  readTextWithin,
+  removeWithin,
+  resolveWithin,
+  writeFileWithin
+});