codetrellis 0.0.0-stage → 0.3.0

package/src/backend/services/plan-doc-guard.js

@@ -0,0 +1,90 @@
+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 plan_doc_guard_exports = {};
+__export(plan_doc_guard_exports, {
+  DISK_TOOL: () => DISK_TOOL,
+  guardDiskEdit: () => guardDiskEdit,
+  settleDiskHold: () => settleDiskHold
+});
+module.exports = __toCommonJS(plan_doc_guard_exports);
+var import_node_crypto = require("node:crypto");
+var import_database = require("./database");
+var import_persistence = require("./persistence");
+var import_breakpoint_service = require("./breakpoint-service");
+var import_agent_event_log = require("./agent-event-log");
+var import_push_notification_service = require("./push-notification-service");
+var import_plan_documents_service = require("./plan-documents-service");
+const DISK_TOOL = "plan-file";
+function waitingHold(docUid) {
+  return (0, import_breakpoint_service.rowsOf)(
+    `SELECT ref FROM breakpoint_hits WHERE item_uid = ? AND action = 'disk' AND answered_at IS NULL ORDER BY hit_at LIMIT 1`,
+    [docUid]
+  )[0]?.ref ?? null;
+}
+function guardDiskEdit(docUid, incoming, now = Date.now()) {
+  const doc = (0, import_plan_documents_service.getPlanDocument)(docUid);
+  if (!doc) return "pass";
+  const title = incoming.title ?? doc.title;
+  if (title === doc.title && incoming.body === doc.body) return "pass";
+  const bp = (0, import_breakpoint_service.docBreakpoint)(docUid);
+  if (!bp) return "pass";
+  const db = (0, import_database.getDb)();
+  const open = waitingHold(docUid);
+  if (open) {
+    db.run("UPDATE plan_doc_disk_holds SET title = ?, body = ?, updated_at = ? WHERE ref = ?", [title, incoming.body, now, open]);
+    (0, import_persistence.markDirty)();
+    return "held";
+  }
+  const ref = `bp-${(0, import_node_crypto.randomBytes)(5).toString("hex")}`;
+  db.run(
+    `INSERT INTO breakpoint_hits (ref, breakpoint_id, tool, action, item_uid, plan_uid, agent, session_id, workstream_root, hit_at)
+     VALUES (?, ?, ?, 'disk', ?, ?, NULL, NULL, NULL, ?)`,
+    [ref, bp.id, DISK_TOOL, docUid, doc.planUid, now]
+  );
+  db.run(
+    "INSERT INTO plan_doc_disk_holds (ref, doc_uid, title, body, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)",
+    [ref, docUid, title, incoming.body, now, now]
+  );
+  (0, import_persistence.markDirty)();
+  const hit = (0, import_breakpoint_service.getHit)(ref);
+  (0, import_agent_event_log.recordBreakpointEvent)("breakpoint_hit", { ...(0, import_breakpoint_service.hitPayload)(hit), breakpointId: bp.id, on: bp.target, onTitle: bp.targetTitle }, null);
+  void (0, import_push_notification_service.pushForBreakpoint)(hit).catch(() => {
+  });
+  return "held";
+}
+function settleDiskHold(hit) {
+  if (hit.action !== "disk" || hit.answeredAt === null) return null;
+  const held = (0, import_breakpoint_service.rowsOf)("SELECT title, body FROM plan_doc_disk_holds WHERE ref = ?", [hit.ref])[0];
+  (0, import_database.getDb)().run("DELETE FROM plan_doc_disk_holds WHERE ref = ?", [hit.ref]);
+  (0, import_persistence.markDirty)();
+  if (hit.decision === "stop" || !held) return "restore";
+  const doc = (0, import_plan_documents_service.updatePlanDocument)(hit.itemUid, {
+    title: held.title,
+    body: held.body,
+    changeSummary: "The file's version, applied from disk when a person continued at the breakpoint",
+    author: hit.answeredBy ?? void 0,
+    authorType: hit.answeredByType ?? void 0
+  });
+  return doc ? "applied" : "restore";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DISK_TOOL,
+  guardDiskEdit,
+  settleDiskHold
+});

package/src/backend/services/plan-documents-service.js

@@ -0,0 +1,275 @@
+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 plan_documents_service_exports = {};
+__export(plan_documents_service_exports, {
+  createPlanDocument: () => createPlanDocument,
+  deletePlanDocument: () => deletePlanDocument,
+  getPlanDocument: () => getPlanDocument,
+  getPlanDocumentByType: () => getPlanDocumentByType,
+  getPlanDocumentVersions: () => getPlanDocumentVersions,
+  listPlanDocumentSummaries: () => listPlanDocumentSummaries,
+  listPlanDocuments: () => listPlanDocuments,
+  searchPlanDocuments: () => searchPlanDocuments,
+  updatePlanDocument: () => updatePlanDocument
+});
+module.exports = __toCommonJS(plan_documents_service_exports);
+var _lazy___plan_file_service = __toESM(require("./plan-file-service"));
+var import_node_crypto = require("node:crypto");
+var import_database = require("./database");
+var import_persistence = require("./persistence");
+var import_agent_event_log = require("./agent-event-log");
+function notifyMutation(planUid) {
+  try {
+    const { scheduleWriteThrough } = _lazy___plan_file_service;
+    scheduleWriteThrough(planUid);
+  } catch {
+  }
+}
+function createPlanDocument(input) {
+  const db = (0, import_database.getDb)();
+  const uid = (0, import_node_crypto.randomUUID)();
+  const now = Date.now();
+  const authorType = input.authorType ?? "human";
+  const orderHint = input.orderHint ?? null;
+  const parentDocUid = input.parentDocUid ?? null;
+  db.run(
+    `INSERT INTO plan_documents (uid, plan_uid, doc_type, title, body, version, author, author_type, order_hint, parent_doc_uid, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?)`,
+    [uid, input.planUid, input.docType, input.title, input.body, input.author, authorType, orderHint, parentDocUid, now, now]
+  );
+  db.run(
+    `INSERT INTO plan_document_versions (doc_uid, version, body, change_summary, author, author_type, created_at)
+     VALUES (?, 1, ?, 'Created', ?, ?, ?)`,
+    [uid, input.body, input.author, authorType, now]
+  );
+  (0, import_persistence.markDirty)();
+  notifyMutation(input.planUid);
+  return {
+    uid,
+    planUid: input.planUid,
+    docType: input.docType,
+    title: input.title,
+    body: input.body,
+    version: 1,
+    author: input.author,
+    authorType,
+    orderHint,
+    parentDocUid,
+    createdAt: now,
+    updatedAt: now
+  };
+}
+function getPlanDocument(docUid) {
+  const result = (0, import_database.getDb)().exec(
+    `SELECT uid, plan_uid, doc_type, title, body, version, author, author_type, order_hint, parent_doc_uid, created_at, updated_at
+     FROM plan_documents WHERE uid = ?`,
+    [docUid]
+  );
+  if (!result[0]?.values[0]) return null;
+  return rowToDoc(result[0].values[0]);
+}
+function getPlanDocumentByType(planUid, docType) {
+  const result = (0, import_database.getDb)().exec(
+    `SELECT uid, plan_uid, doc_type, title, body, version, author, author_type, order_hint, parent_doc_uid, created_at, updated_at
+     FROM plan_documents WHERE plan_uid = ? AND doc_type = ?
+     ORDER BY updated_at DESC LIMIT 1`,
+    [planUid, docType]
+  );
+  if (!result[0]?.values[0]) return null;
+  return rowToDoc(result[0].values[0]);
+}
+function listPlanDocuments(planUid) {
+  const result = (0, import_database.getDb)().exec(
+    `SELECT uid, plan_uid, doc_type, title, body, version, author, author_type, order_hint, parent_doc_uid, created_at, updated_at
+     FROM plan_documents WHERE plan_uid = ?
+     ORDER BY
+       CASE WHEN parent_doc_uid IS NULL THEN 0 ELSE 1 END,
+       COALESCE(order_hint, '~'),
+       doc_type,
+       updated_at DESC`,
+    [planUid]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map(rowToDoc);
+}
+function listPlanDocumentSummaries(planUid) {
+  const result = (0, import_database.getDb)().exec(
+    `SELECT uid, doc_type, title, version, length(body), order_hint, parent_doc_uid, updated_at
+     FROM plan_documents WHERE plan_uid = ?
+     ORDER BY
+       CASE WHEN parent_doc_uid IS NULL THEN 0 ELSE 1 END,
+       COALESCE(order_hint, '~'),
+       doc_type,
+       updated_at DESC`,
+    [planUid]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map((r) => ({
+    uid: r[0],
+    docType: r[1],
+    title: r[2],
+    version: r[3],
+    bodyLength: r[4] || 0,
+    orderHint: r[5] ?? null,
+    parentDocUid: r[6] ?? null,
+    updatedAt: r[7]
+  }));
+}
+function updatePlanDocument(docUid, updates) {
+  const db = (0, import_database.getDb)();
+  const existing = getPlanDocument(docUid);
+  if (!existing) return null;
+  const now = Date.now();
+  const sets = ["updated_at = ?"];
+  const params = [now];
+  const bodyChanged = updates.body !== void 0 && updates.body !== existing.body;
+  if (updates.title !== void 0) {
+    sets.push("title = ?");
+    params.push(updates.title);
+  }
+  if (updates.docType !== void 0) {
+    sets.push("doc_type = ?");
+    params.push(updates.docType);
+  }
+  if (updates.orderHint !== void 0) {
+    sets.push("order_hint = ?");
+    params.push(updates.orderHint);
+  }
+  if (updates.parentDocUid !== void 0) {
+    sets.push("parent_doc_uid = ?");
+    params.push(updates.parentDocUid);
+  }
+  if (bodyChanged) {
+    sets.push("body = ?");
+    params.push(updates.body);
+    sets.push("version = version + 1");
+  }
+  params.push(docUid);
+  db.run(`UPDATE plan_documents SET ${sets.join(", ")} WHERE uid = ?`, params);
+  if (bodyChanged) {
+    const author = updates.author ?? existing.author;
+    const authorType = updates.author !== void 0 ? updates.authorType ?? null : existing.authorType ?? null;
+    db.run(
+      `INSERT INTO plan_document_versions (doc_uid, version, body, change_summary, author, author_type, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [docUid, existing.version + 1, updates.body, updates.changeSummary ?? "Updated", author, authorType, now]
+    );
+    (0, import_agent_event_log.recordBodyEdit)({
+      kind: "document",
+      planUid: existing.planUid,
+      uid: docUid,
+      title: updates.title ?? existing.title,
+      version: existing.version + 1,
+      author: updates.author !== void 0 ? updates.author ?? null : null,
+      // No author: the plan file was re-read from disk.
+      authorType: updates.author !== void 0 ? updates.authorType ?? null : "file",
+      changeSummary: updates.changeSummary ?? null
+    });
+  }
+  (0, import_persistence.markDirty)();
+  notifyMutation(existing.planUid);
+  return getPlanDocument(docUid);
+}
+function deletePlanDocument(docUid) {
+  const db = (0, import_database.getDb)();
+  const before = getPlanDocument(docUid);
+  db.run(`DELETE FROM plan_document_versions WHERE doc_uid = ?`, [docUid]);
+  db.run(`DELETE FROM plan_documents WHERE uid = ?`, [docUid]);
+  (0, import_persistence.markDirty)();
+  if (before) notifyMutation(before.planUid);
+}
+function searchPlanDocuments(planUid, query) {
+  if (!query.trim()) return [];
+  const result = (0, import_database.getDb)().exec(
+    `SELECT uid, plan_uid, doc_type, title, body, version, author, author_type, order_hint, parent_doc_uid, created_at, updated_at
+     FROM plan_documents
+     WHERE plan_uid = ? AND (title LIKE ? OR body LIKE ?)
+     ORDER BY updated_at DESC LIMIT 25`,
+    [planUid, `%${query}%`, `%${query}%`]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map((r) => {
+    const doc = rowToDoc(r);
+    return { doc, excerpt: makeExcerpt(doc.body, query) };
+  });
+}
+function getPlanDocumentVersions(docUid) {
+  const result = (0, import_database.getDb)().exec(
+    `SELECT id, doc_uid, version, body, change_summary, author, created_at, author_type
+     FROM plan_document_versions WHERE doc_uid = ?
+     ORDER BY version DESC`,
+    [docUid]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map((r) => ({
+    id: r[0],
+    docUid: r[1],
+    version: r[2],
+    body: r[3],
+    changeSummary: r[4] ?? null,
+    author: r[5],
+    createdAt: r[6],
+    authorType: r[7] ?? null
+  }));
+}
+function rowToDoc(r) {
+  return {
+    uid: r[0],
+    planUid: r[1],
+    docType: r[2],
+    title: r[3],
+    body: r[4],
+    version: r[5],
+    author: r[6],
+    authorType: r[7],
+    orderHint: r[8] ?? null,
+    parentDocUid: r[9] ?? null,
+    createdAt: r[10],
+    updatedAt: r[11]
+  };
+}
+function makeExcerpt(body, query, radius = 80) {
+  if (!body) return "";
+  const idx = body.toLowerCase().indexOf(query.toLowerCase());
+  if (idx === -1) return body.slice(0, radius * 2) + (body.length > radius * 2 ? "\u2026" : "");
+  const start = Math.max(0, idx - radius);
+  const end = Math.min(body.length, idx + query.length + radius);
+  return (start > 0 ? "\u2026" : "") + body.slice(start, end) + (end < body.length ? "\u2026" : "");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createPlanDocument,
+  deletePlanDocument,
+  getPlanDocument,
+  getPlanDocumentByType,
+  getPlanDocumentVersions,
+  listPlanDocumentSummaries,
+  listPlanDocuments,
+  searchPlanDocuments,
+  updatePlanDocument
+});

package/src/backend/services/plan-event-service.js

@@ -0,0 +1,154 @@
+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 plan_event_service_exports = {};
+__export(plan_event_service_exports, {
+  appendPlanEvent: () => appendPlanEvent,
+  getNewestEventTimestamp: () => getNewestEventTimestamp,
+  listItemEvents: () => listItemEvents,
+  listPlanEvents: () => listPlanEvents,
+  setPlanEventListener: () => setPlanEventListener
+});
+module.exports = __toCommonJS(plan_event_service_exports);
+var import_database = require("./database");
+var import_persistence = require("./persistence");
+let eventListener = null;
+function setPlanEventListener(fn) {
+  eventListener = fn;
+}
+function appendPlanEvent(input) {
+  const db = (0, import_database.getDb)();
+  const now = input.createdAt ?? Date.now();
+  const beforeJson = input.beforeState !== void 0 ? JSON.stringify(input.beforeState) : null;
+  const afterJson = input.afterState !== void 0 ? JSON.stringify(input.afterState) : null;
+  db.run(
+    `INSERT INTO plan_events
+       (plan_uid, item_uid, event_type, before_state, after_state, summary, author, author_type, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      input.planUid,
+      input.itemUid ?? null,
+      input.eventType,
+      beforeJson,
+      afterJson,
+      input.summary,
+      input.author,
+      input.authorType,
+      now
+    ]
+  );
+  const idResult = db.exec(`SELECT last_insert_rowid()`);
+  const id = idResult[0]?.values[0]?.[0] ?? -1;
+  (0, import_persistence.markDirty)();
+  const event = {
+    id,
+    planUid: input.planUid,
+    itemUid: input.itemUid ?? null,
+    eventType: input.eventType,
+    beforeState: input.beforeState,
+    afterState: input.afterState,
+    summary: input.summary,
+    author: input.author,
+    authorType: input.authorType,
+    createdAt: now
+  };
+  try {
+    eventListener?.(event);
+  } catch {
+  }
+  return event;
+}
+function listPlanEvents(planUid, options = {}) {
+  const db = (0, import_database.getDb)();
+  const params = [planUid];
+  let where = `plan_uid = ?`;
+  if (options.sinceMs !== void 0) {
+    where += ` AND created_at >= ?`;
+    params.push(options.sinceMs);
+  }
+  if (options.eventTypes && options.eventTypes.length > 0) {
+    where += ` AND event_type IN (${options.eventTypes.map(() => "?").join(", ")})`;
+    for (const t of options.eventTypes) params.push(t);
+  }
+  const limit = options.limit ?? 500;
+  const offset = options.offset ?? 0;
+  params.push(limit, offset);
+  const result = db.exec(
+    `SELECT id, plan_uid, item_uid, event_type, before_state, after_state, summary, author, author_type, created_at
+     FROM plan_events
+     WHERE ${where}
+     ORDER BY created_at DESC
+     LIMIT ? OFFSET ?`,
+    params
+  );
+  if (!result[0]) return [];
+  return result[0].values.map(rowToEvent);
+}
+function listItemEvents(itemUid, options = {}) {
+  const db = (0, import_database.getDb)();
+  const limit = options.limit ?? 200;
+  const offset = options.offset ?? 0;
+  const result = db.exec(
+    `SELECT id, plan_uid, item_uid, event_type, before_state, after_state, summary, author, author_type, created_at
+     FROM plan_events
+     WHERE item_uid = ?
+     ORDER BY created_at DESC
+     LIMIT ? OFFSET ?`,
+    [itemUid, limit, offset]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map(rowToEvent);
+}
+function getNewestEventTimestamp(planUid) {
+  const db = (0, import_database.getDb)();
+  const result = db.exec(
+    `SELECT MAX(created_at) FROM plan_events WHERE plan_uid = ?`,
+    [planUid]
+  );
+  const v = result[0]?.values[0]?.[0];
+  return typeof v === "number" ? v : null;
+}
+function rowToEvent(r) {
+  return {
+    id: r[0],
+    planUid: r[1],
+    itemUid: r[2] ?? null,
+    eventType: r[3],
+    beforeState: parseJsonSafe(r[4]),
+    afterState: parseJsonSafe(r[5]),
+    summary: r[6],
+    author: r[7],
+    authorType: r[8],
+    createdAt: r[9]
+  };
+}
+function parseJsonSafe(s) {
+  if (!s) return void 0;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return void 0;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  appendPlanEvent,
+  getNewestEventTimestamp,
+  listItemEvents,
+  listPlanEvents,
+  setPlanEventListener
+});

package/src/backend/services/plan-file-refs.js

@@ -0,0 +1,106 @@
+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 plan_file_refs_exports = {};
+__export(plan_file_refs_exports, {
+  cleanRefs: () => cleanRefs,
+  importItemRefs: () => importItemRefs,
+  importPlanRefs: () => importPlanRefs,
+  refsForItem: () => refsForItem,
+  refsForPlan: () => refsForPlan
+});
+module.exports = __toCommonJS(plan_file_refs_exports);
+var import_external_intake_service = require("./external-intake-service");
+var import_external_refs_service = require("./external-refs-service");
+const MAX_REFS = 50;
+const KINDS = /* @__PURE__ */ new Set(["github_issue", "github_pr", "github_commit", "jira", "linear", "figma", "notion", "slack", "url"]);
+const KEY = /^[A-Za-z0-9][A-Za-z0-9_.#/-]{0,99}$/;
+const IMPORTED = { author: "file-import", authorType: "system" };
+function cleanRefs(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const r of raw.slice(0, MAX_REFS)) {
+    if (!r || typeof r !== "object") continue;
+    const { url, key, kind, title } = r;
+    if (typeof url !== "string" || url.length > 2048) continue;
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      continue;
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") continue;
+    if (out.some((o) => (0, import_external_intake_service.sameUrl)(o.url, url))) continue;
+    out.push({
+      url,
+      key: typeof key === "string" && KEY.test(key) ? key : null,
+      kind: typeof kind === "string" && KINDS.has(kind) ? kind : (0, import_external_refs_service.inferKind)(url),
+      title: typeof title === "string" && title.trim() ? title.trim().slice(0, 200) : null
+    });
+  }
+  return out;
+}
+const fileRef = (r) => ({
+  url: r.url,
+  ...r.externalKey ? { key: r.externalKey } : {},
+  kind: r.kind,
+  ...r.title && r.title !== r.url && r.title !== r.externalKey ? { title: r.title } : {}
+});
+function refsForPlan(planUid) {
+  try {
+    return (0, import_external_intake_service.getPlanExternalRefs)(planUid).map(fileRef);
+  } catch {
+    return [];
+  }
+}
+function refsForItem(itemUid) {
+  try {
+    return (0, import_external_refs_service.getExternalRefs)(itemUid).map(fileRef);
+  } catch {
+    return [];
+  }
+}
+function importPlanRefs(planUid, raw) {
+  let n = 0;
+  for (const r of cleanRefs(raw)) {
+    (0, import_external_intake_service.setPlanExternalRef)({ planUid, url: r.url, key: r.key, kind: r.kind, ...r.title ? { title: r.title } : {}, ...IMPORTED });
+    n++;
+  }
+  return n;
+}
+function importItemRefs(itemUid, raw) {
+  const have = (0, import_external_refs_service.getExternalRefs)(itemUid);
+  let n = 0;
+  for (const r of cleanRefs(raw)) {
+    const existing = have.find((h) => (0, import_external_intake_service.sameUrl)(h.url, r.url));
+    if (existing) {
+      if (r.title && r.title !== existing.title) (0, import_external_refs_service.updateExternalRef)(existing.uid, { title: r.title });
+      continue;
+    }
+    (0, import_external_refs_service.createExternalRef)({ itemUid, url: r.url, kind: r.kind, externalKey: r.key, ...r.title ? { title: r.title } : {}, ...IMPORTED });
+    n++;
+  }
+  return n;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cleanRefs,
+  importItemRefs,
+  importPlanRefs,
+  refsForItem,
+  refsForPlan
+});