clay-server 4.0.0-beta.2 → 4.0.0-beta.21

package/lib/project-logs-query.js

@@ -0,0 +1,185 @@
+// Query, ranking, and pagination for Project Logs.
+//
+// Extracted from project-logs-store.js so the store stays focused on records
+// and stays inside the module size limit. Ranking uses the shared BM25 adapter,
+// which wraps Clay's single ranking engine; the response shapes, filters,
+// pagination, and tie-breaks are exactly what the store returned before.
+
+var knowledgeSearch = require("./knowledge-search");
+
+var MAX_PAGE = 50;
+var DEFAULT_PAGE = 20;
+var MAX_SNIPPET_CHARS = 320;
+
+// Title and tags outrank body text, expressed as repetition for BM25.
+var TITLE_WEIGHT = 3;
+// A summary is a human-written distillation of the whole record, so it ranks
+// between the title and the raw body.
+var SUMMARY_WEIGHT = 2;
+var TAG_WEIGHT = 2;
+var BODY_WEIGHT = 1;
+
+// Locale-independent lexical order over UTF-16 code units.
+//
+// An opaque ref is base64url, so it contains both "-" (0x2D) and "_" (0x5F).
+// String.prototype.localeCompare applies collation rules that order those two
+// the other way round from code-unit order, and the result varies by ICU data,
+// so it cannot be the basis of a documented deterministic tie-break. This
+// matches the default Array.prototype.sort ordering exactly.
+function compareRefs(a, b) {
+  var left = String(a);
+  var right = String(b);
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function parseLimit(value) {
+  var limit = Number(value);
+  if (!Number.isFinite(limit)) limit = DEFAULT_PAGE;
+  return Math.max(1, Math.min(MAX_PAGE, Math.floor(limit)));
+}
+
+function encodeCursor(offset) {
+  return offset > 0 ? Buffer.from(String(offset), "utf8").toString("base64url") : null;
+}
+
+function decodeCursor(value) {
+  if (!value) return 0;
+  try {
+    var parsed = Number(Buffer.from(String(value), "base64url").toString("utf8"));
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
+  } catch (e) {
+    return 0;
+  }
+}
+
+function page(items, args) {
+  var offset = decodeCursor(args && args.cursor);
+  var limit = parseLimit(args && args.limit);
+  return {
+    items: items.slice(offset, offset + limit),
+    nextCursor: offset + limit < items.length ? encodeCursor(offset + limit) : null,
+    total: items.length,
+  };
+}
+
+function contextMode(options) {
+  var value = options && options.contextMode;
+  return value === "all" || value === "current" || value === "project" ? value : "all";
+}
+
+function matchesContext(entry, options) {
+  var mode = contextMode(options);
+  var changeSetId = entry && entry.context && entry.context.changeSetId;
+  if (mode === "all") return true;
+  if (mode === "project") return !changeSetId;
+  return !changeSetId || changeSetId === options.currentChangeSetId;
+}
+
+function listEntries(entries, args, cleanLine, validateKind) {
+  var options = args || {};
+  var kind = options.kind ? validateKind(options.kind, null) : null;
+  var tag = options.tag ? cleanLine(String(options.tag), 40).toLowerCase() : null;
+  var priority = options.priority ? String(options.priority) : null;
+  var filtered = entries.filter(function (entry) {
+    // Exact match on the project's own vocabulary. A well-formed category this
+    // project has never used simply matches nothing.
+    if (kind && entry.category !== kind) return false;
+    if (priority && entry.priority !== priority) return false;
+    if (tag && entry.tags.indexOf(tag) === -1) return false;
+    if (!matchesContext(entry, options)) return false;
+    return true;
+  });
+  var result = page(filtered, options);
+  return {
+    entries: result.items.map(summarize),
+    nextCursor: result.nextCursor,
+    total: result.total,
+  };
+}
+
+function projectEntry(entry) {
+  return {
+    id: entry.ref,
+    fields: [
+      { text: entry.title, weight: TITLE_WEIGHT },
+      { text: entry.summary || "", weight: SUMMARY_WEIGHT },
+      { text: (entry.tags || []).join(" "), weight: TAG_WEIGHT },
+      { text: entry.body, weight: BODY_WEIGHT },
+    ],
+    meta: entry,
+  };
+}
+
+// The ledger row. Everything needed to understand an entry at a glance, and
+// never the body: a list must not dump record contents.
+function summarize(entry) {
+  return {
+    ref: entry.ref,
+    kind: entry.kind,
+    category: entry.category,
+    priority: entry.priority,
+    title: entry.title,
+    summary: entry.summary || "",
+    tags: entry.tags,
+    createdAt: entry.createdAt,
+    createdBy: entry.createdBy,
+    updatedAt: entry.updatedAt,
+    updatedBy: entry.updatedBy,
+    revisions: entry.revisions,
+    commentCount: entry.commentCount || 0,
+    // How many comments still await Driver review. A count only: the ledger
+    // never carries comment bodies.
+    pendingFeedbackCount: entry.pendingFeedbackCount || 0,
+    context: entry.context || null,
+  };
+}
+
+function searchEntries(entries, args, cleanLine, validateKind) {
+  var options = args || {};
+  var query = cleanLine(options.query || "", 200);
+  if (!query) throw new Error("A search query is required.");
+  var kind = options.kind ? validateKind(options.kind, null) : null;
+  var priority = options.priority ? String(options.priority) : null;
+  var candidates = entries.filter(function (entry) {
+    if (kind && entry.category !== kind) return false;
+    if (priority && entry.priority !== priority) return false;
+    if (!matchesContext(entry, options)) return false;
+    return true;
+  });
+
+  var ranked = knowledgeSearch.rank(candidates, query, projectEntry, candidates.length);
+  var hits = [];
+  for (var i = 0; i < ranked.length; i++) {
+    var entry = ranked[i].meta;
+    var hit = summarize(entry);
+    hit.score = ranked[i].score;
+    hit.snippet = cleanLine(knowledgeSearch.snippet(entry.body, query, MAX_SNIPPET_CHARS), MAX_SNIPPET_CHARS);
+    hits.push(hit);
+  }
+  // Deterministic ordering: score, then most recent, then a stable ref.
+  hits.sort(function (a, b) {
+    return b.score - a.score || b.updatedAt - a.updatedAt || compareRefs(a.ref, b.ref);
+  });
+  var result = page(hits, options);
+  return { results: result.items, nextCursor: result.nextCursor, total: result.total };
+}
+
+module.exports = {
+  compareRefs: compareRefs,
+  MAX_PAGE: MAX_PAGE,
+  DEFAULT_PAGE: DEFAULT_PAGE,
+  MAX_SNIPPET_CHARS: MAX_SNIPPET_CHARS,
+  TITLE_WEIGHT: TITLE_WEIGHT,
+  SUMMARY_WEIGHT: SUMMARY_WEIGHT,
+  TAG_WEIGHT: TAG_WEIGHT,
+  BODY_WEIGHT: BODY_WEIGHT,
+  parseLimit: parseLimit,
+  encodeCursor: encodeCursor,
+  decodeCursor: decodeCursor,
+  page: page,
+  contextMode: contextMode,
+  matchesContext: matchesContext,
+  summarize: summarize,
+  listEntries: listEntries,
+  searchEntries: searchEntries,
+};

package/lib/project-logs-root.js

@@ -0,0 +1,75 @@
+// Project root resolution for Project Logs storage.
+//
+// Split from project-logs-store.js so the store stays inside the module size
+// limit. A worktree shares its parent project's Logs: the store root is
+// resolved through Git's common directory, so a worktree session and a parent
+// session read and write the same record file instead of forking knowledge.
+
+var fs = require("fs");
+var path = require("path");
+var execFileSync = require("child_process").execFileSync;
+var utils = require("./utils");
+
+var _rootCache = new Map();
+
+function defaultGit(cwd, args) {
+  return execFileSync("git", args, {
+    cwd: cwd,
+    encoding: "utf8",
+    timeout: 5000,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+}
+
+// Symlinked paths must collapse to one identity. Git reports a worktree's
+// common directory in real terms while a project path may arrive symlinked
+// (/var vs /private/var on macOS), and two spellings of one root would fork
+// the Logs, which is precisely what worktree sharing exists to prevent.
+function canonicalPath(value) {
+  var resolved = path.resolve(value);
+  try {
+    return fs.realpathSync.native(resolved);
+  } catch (e) {
+    return resolved;
+  }
+}
+
+// A worktree's common directory points at the parent checkout's .git, so its
+// parent working tree is that directory's parent. Anything that is not an
+// ordinary .git directory (bare-backed worktrees, non-Git folders) falls back
+// to the path itself rather than guessing.
+function resolveProjectRoot(cwd, runGit) {
+  var resolved = canonicalPath(cwd);
+  if (!runGit && _rootCache.has(resolved)) return _rootCache.get(resolved);
+  var root = resolved;
+  try {
+    var commonDir = (runGit || defaultGit)(resolved, ["rev-parse", "--git-common-dir"]);
+    var absoluteCommon = path.resolve(resolved, String(commonDir || "").trim());
+    if (path.basename(absoluteCommon) === ".git") {
+      var parent = path.dirname(absoluteCommon);
+      if (fs.statSync(parent).isDirectory()) root = canonicalPath(parent);
+    }
+  } catch (e) {
+    root = resolved;
+  }
+  if (!runGit) _rootCache.set(resolved, root);
+  return root;
+}
+
+function scopeIdForRoot(root) {
+  return "project/" + utils.encodeCwd(root);
+}
+
+function scopeIdForKnowledgeId(knowledgeId) {
+  if (typeof knowledgeId !== "string" || !/^[A-Za-z0-9_-]{1,120}$/.test(knowledgeId)) {
+    throw new Error("Invalid project knowledge id.");
+  }
+  return "project/" + knowledgeId;
+}
+
+module.exports = {
+  resolveProjectRoot: resolveProjectRoot,
+  scopeIdForRoot: scopeIdForRoot,
+  scopeIdForKnowledgeId: scopeIdForKnowledgeId,
+  canonicalPath: canonicalPath,
+};

package/lib/project-logs-schema.js

@@ -0,0 +1,259 @@
+// Vocabulary and validation for Project Logs.
+//
+// Extracted from project-logs-store.js so the store stays focused on records
+// and stays inside the module size limit.
+//
+// Two independent axes, deliberately:
+//   category - what kind of record this is, a project-local vocabulary
+//   priority - how much it matters, a stable global enum
+// Conflating them is what made "an urgent decision" unrepresentable before.
+//
+// Category is NOT a global enum. Every project evolves its own vocabulary: an
+// agent reuses an established category when one fits and coins a new one when
+// the project needs a durable distinction it does not yet have. What is fixed
+// is only the shape of a category label, not the set of labels. The seeds
+// below are guidance for a project with no history yet, never a whitelist.
+
+// Suggested starting points, surfaced in tool guidance only.
+var SEED_CATEGORIES = [
+  "decision",
+  "security",
+  "idea",
+  "operations",
+  "incident",
+  "investigation",
+  "progress",
+  "reference",
+];
+
+var MAX_CATEGORY_CHARS = 32;
+// Letters and digits in any script, so a project can keep its vocabulary in the
+// language it actually works in. Normalization runs server-side only, so this
+// depends on Node's Unicode property escapes and never on a browser baseline.
+var CATEGORY_PATTERN = /^[\p{L}\p{N}]+(?:-[\p{L}\p{N}]+)*$/u;
+var CATEGORY_STRIP = /[^\p{L}\p{N}-]/gu;
+
+// Length is counted in code points, not UTF-16 units, so a CJK or Hangul label
+// is bounded the same way a Latin one is.
+function codePointLength(value) {
+  return Array.from(value).length;
+}
+
+// Deterministic normalization to a lowercase, hyphen-separated label. Anything
+// that cannot be reduced to a safe label is rejected rather than silently
+// coerced, so a caller is told when its input was unusable instead of getting a
+// surprising slug.
+//
+// Path and identity shapes are refused outright: a category is dry metadata and
+// must never be able to carry a slug, a path segment, or a user id.
+function normalizeCategory(value) {
+  if (typeof value !== "string") throw new Error("A log category must be a string.");
+  var raw = value.normalize("NFC").trim();
+  if (!raw) throw new Error("A log category is required.");
+  if (codePointLength(raw) > MAX_CATEGORY_CHARS * 2) {
+    throw new Error("A log category must be " + MAX_CATEGORY_CHARS + " characters or fewer.");
+  }
+  if (/[\/\\]/.test(raw) || raw.indexOf("..") !== -1) {
+    throw new Error("A log category cannot contain path characters.");
+  }
+  var slug = raw
+    .toLowerCase()
+    .replace(/[_\s]+/g, "-")
+    .replace(CATEGORY_STRIP, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  if (!slug) throw new Error("A log category must contain letters or digits: " + value);
+  if (codePointLength(slug) > MAX_CATEGORY_CHARS) {
+    throw new Error("A log category must be " + MAX_CATEGORY_CHARS + " characters or fewer.");
+  }
+  if (!CATEGORY_PATTERN.test(slug)) throw new Error("Invalid log category: " + value);
+  return slug;
+}
+
+// Non-throwing form for reading stored records, where a corrupt on-disk value
+// should make that record unusable rather than break the whole projection.
+// Filters deliberately do NOT use this: a caller that supplies a malformed
+// category is told so.
+function safeCategory(value) {
+  try {
+    return normalizeCategory(value);
+  } catch (e) {
+    return null;
+  }
+}
+
+var PRIORITIES = ["normal", "important", "urgent"];
+var DEFAULT_PRIORITY = "normal";
+
+var MAX_SUMMARY_CHARS = 400;
+
+function isPriority(value) {
+  return PRIORITIES.indexOf(value) !== -1;
+}
+
+function normalizePriority(value) {
+  return isPriority(value) ? value : DEFAULT_PRIORITY;
+}
+
+// A summary for an entry written before summaries existed. Deterministic and
+// derived from stored content only, so the same record always yields the same
+// text and nothing is invented.
+function fallbackSummary(entry) {
+  if (!entry) return "";
+  if (typeof entry.summary === "string" && entry.summary.trim()) {
+    return entry.summary.trim().substring(0, MAX_SUMMARY_CHARS);
+  }
+  // Prefer the first line of prose. A leading Markdown heading usually just
+  // restates the title, so it is only used when there is nothing else.
+  var body = typeof entry.body === "string" ? entry.body : "";
+  var lines = body.split("\n");
+  var heading = "";
+  var firstLine = "";
+  for (var i = 0; i < lines.length; i++) {
+    var raw = lines[i].trim();
+    if (!raw) continue;
+    var isHeading = raw.charAt(0) === "#";
+    var line = raw.replace(/^#+\s*/, "").replace(/^[-*>]\s*/, "").trim();
+    if (!line) continue;
+    if (isHeading) {
+      if (!heading) heading = line;
+      continue;
+    }
+    firstLine = line;
+    break;
+  }
+  if (!firstLine) firstLine = heading;
+  if (!firstLine) return "";
+  return firstLine.length > MAX_SUMMARY_CHARS
+    ? firstLine.substring(0, MAX_SUMMARY_CHARS)
+    : firstLine;
+}
+
+// Validation for a new agent-written record. Category, title, and summary are
+// all required: a log without a summary cannot be understood from a list, and
+// that is the whole point of the surface.
+function validateNewRecord(input) {
+  var data = input || {};
+  var category = normalizeCategory(data.category || data.kind);
+  if (typeof data.title !== "string" || !data.title.trim()) throw new Error("A log title is required.");
+  if (typeof data.summary !== "string" || !data.summary.trim()) {
+    throw new Error("A one or two sentence summary is required so the entry is understandable from a list.");
+  }
+  // A mistyped priority is refused rather than silently downgraded to normal:
+  // an agent that meant "urgent" must not get "normal" without being told.
+  if (data.priority !== undefined && data.priority !== null && !isPriority(data.priority)) {
+    throw new Error("Unknown log priority: " + data.priority);
+  }
+  return {
+    category: category,
+    priority: normalizePriority(data.priority),
+  };
+}
+
+// Validation for a revision. The category may move to another writable value
+// or stay on its legacy one; nothing is required, but nothing may be emptied.
+function validateRevision(input) {
+  var data = input || {};
+  var out = {};
+  if (data.category !== undefined || data.kind !== undefined) {
+    out.category = normalizeCategory(data.category || data.kind);
+  }
+  if (data.priority !== undefined) {
+    if (!isPriority(data.priority)) throw new Error("Unknown log priority: " + data.priority);
+    out.priority = data.priority;
+  }
+  if (data.title !== undefined) {
+    if (typeof data.title !== "string" || !data.title.trim()) throw new Error("A log title cannot be emptied.");
+    out.title = data.title;
+  }
+  if (data.summary !== undefined) {
+    if (typeof data.summary !== "string" || !data.summary.trim()) throw new Error("A log summary cannot be emptied.");
+    out.summary = data.summary;
+  }
+  return out;
+}
+
+
+// --- Normalization -------------------------------------------------------
+//
+// Moved here from project-logs-store.js so the store stays inside the module
+// size limit. These are pure text and shape helpers with no record semantics.
+
+var MAX_TAGS = 12;
+var MAX_TAG_CHARS = 40;
+var MAX_LINKS = 20;
+var MAX_LINK_CHARS = 200;
+
+function cleanText(value, max) {
+  if (typeof value !== "string") return "";
+  var text = value.replace(/\u0000/g, "").trim();
+  return text.length > max ? text.substring(0, max) : text;
+}
+
+function cleanLine(value, max) {
+  return cleanText(value, max).replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function normalizeAuthor(author) {
+  var source = author || {};
+  var type = source.type === "user" ? "user" : "session";
+  return {
+    type: type,
+    userId: source.userId ? cleanLine(String(source.userId), 120) : null,
+    displayName: cleanLine(source.displayName || "", 120) || null,
+    sessionKey: source.sessionKey ? cleanLine(String(source.sessionKey), 200) : null,
+    vendor: cleanLine(source.vendor || "", 40) || null,
+  };
+}
+
+function normalizeTags(tags) {
+  if (!Array.isArray(tags)) return [];
+  var out = [];
+  for (var i = 0; i < tags.length && out.length < MAX_TAGS; i++) {
+    var tag = cleanLine(String(tags[i] == null ? "" : tags[i]), MAX_TAG_CHARS).toLowerCase();
+    if (tag && out.indexOf(tag) === -1) out.push(tag);
+  }
+  return out;
+}
+
+function normalizeLinks(links) {
+  if (!Array.isArray(links)) return [];
+  var out = [];
+  for (var i = 0; i < links.length && out.length < MAX_LINKS; i++) {
+    var raw = links[i];
+    var value = typeof raw === "string" ? { ref: raw } : (raw || {});
+    var ref = cleanLine(String(value.ref || value.sessionRef || ""), MAX_LINK_CHARS);
+    if (!ref) continue;
+    var label = cleanLine(value.label || "", MAX_LINK_CHARS) || null;
+    var duplicate = false;
+    for (var j = 0; j < out.length; j++) {
+      if (out[j].ref === ref) { duplicate = true; break; }
+    }
+    if (!duplicate) out.push({ ref: ref, label: label });
+  }
+  return out;
+}
+
+module.exports = {
+  SEED_CATEGORIES: SEED_CATEGORIES,
+  MAX_CATEGORY_CHARS: MAX_CATEGORY_CHARS,
+  CATEGORY_PATTERN: CATEGORY_PATTERN,
+  codePointLength: codePointLength,
+  normalizeCategory: normalizeCategory,
+  safeCategory: safeCategory,
+  PRIORITIES: PRIORITIES,
+  DEFAULT_PRIORITY: DEFAULT_PRIORITY,
+  MAX_SUMMARY_CHARS: MAX_SUMMARY_CHARS,
+  isPriority: isPriority,
+  normalizePriority: normalizePriority,
+  fallbackSummary: fallbackSummary,
+  MAX_TAGS: MAX_TAGS,
+  MAX_LINKS: MAX_LINKS,
+  cleanText: cleanText,
+  cleanLine: cleanLine,
+  normalizeAuthor: normalizeAuthor,
+  normalizeTags: normalizeTags,
+  normalizeLinks: normalizeLinks,
+  validateNewRecord: validateNewRecord,
+  validateRevision: validateRevision,
+};