drafted 1.18.1 → 1.18.2

package/src/shared/gate-budget.mjs

@@ -0,0 +1,30 @@
+// Single source of truth for the per-project auto-inject context budget.
+// Shared by the MCP gate logic (mcp/gates.mjs) and the server-side deposit caps
+// (server/lib/project-skill-routes.mjs) so web-remote, local-stdio, and raw-API
+// callers all enforce the same limit. ~24k chars ≈ 6k tokens.
+export const PROJECT_CONTEXT_BUDGET_CHARS = 24000;
+
+function gateItemChars(it) {
+  if (it && typeof it === 'object') {
+    if (it.content != null) return String(it.content).length;
+    if (typeof it.chars === 'number') return it.chars;
+  }
+  if (typeof it === 'string') return it.length;
+  if (typeof it === 'number') return it;
+  return 0;
+}
+
+// Greedily include items whose sizes fit the budget (in priority order); defer the
+// rest. Shared by the server-side project-open priming assembly and the MCP gate
+// fallback so both produce identical auto-inject sets.
+export function selectWithinBudget(items, budget = PROJECT_CONTEXT_BUDGET_CHARS, sizeOf = gateItemChars) {
+  const included = [];
+  const deferred = [];
+  let used = 0;
+  for (const it of items || []) {
+    const size = sizeOf(it);
+    if (used + size <= budget) { included.push(it); used += size; }
+    else { deferred.push(it); }
+  }
+  return { included, deferred, used, budget };
+}

package/src/shared/minion-presets.mjs

@@ -0,0 +1,67 @@
+// Deploy-seeded starting points for the Minion builder ("presets"). Pure data,
+// shared for every org (no per-org copy). Each preset pre-wires the builder
+// config for a use case; the user then edits any field. `config: null` means
+// the full blank/advanced form. See feature card: contexts/minions/feature-card.
+//
+// A preset's `config` is a partial minion the builder hydrates via showConfig:
+//   { description, checklist:[{label,evidence,required}], output:{mode,grouping,format,register} }
+// Drive-only bits (format:google-*, register) degrade to a markdown record when
+// the org has no Google Drive connected — the builder simply hides those fields.
+export const MINION_PRESETS = [
+  {
+    key: 'reports-sheet',
+    name: 'Collect reports → spreadsheet',
+    icon: '▤',
+    tagline: 'A form people fill out. Each one becomes a document + a new row in a master sheet.',
+    config: {
+      description: '',
+      checklist: [
+        { label: 'Department', evidence: 'text', required: true },
+        { label: 'What happened', evidence: 'text', required: true },
+        { label: 'Attachment (file or photo)', evidence: 'file', required: false },
+      ],
+      output: {
+        mode: 'generate',
+        grouping: 'frame',
+        format: 'google-doc',
+        register: { columns: ['Date', 'Department', 'Summary', 'Report link'] },
+      },
+    },
+  },
+  {
+    key: 'files',
+    name: 'Gather files / evidence',
+    icon: '▦',
+    tagline: 'Collect photos & documents into one organized folder, with a short summary.',
+    config: {
+      description: '',
+      checklist: [
+        { label: 'Files or photos', evidence: 'file', required: true },
+        { label: 'A short note about them', evidence: 'text', required: false },
+      ],
+      output: { mode: 'generate', grouping: 'lane' },
+    },
+  },
+  {
+    key: 'survey',
+    name: 'Survey / intake form',
+    icon: '≡',
+    tagline: 'Ask a set of questions. One tidy record per response.',
+    config: {
+      description: '',
+      checklist: [
+        { label: 'Question 1', evidence: 'text', required: true },
+        { label: 'Question 2', evidence: 'text', required: true },
+        { label: 'Question 3', evidence: 'text', required: false },
+      ],
+      output: { mode: 'generate', grouping: 'frame' },
+    },
+  },
+  {
+    key: 'blank',
+    name: 'Blank (advanced)',
+    icon: '+',
+    tagline: 'Start from raw settings — full control.',
+    config: null,
+  },
+];

package/src/shared/okf-log.mjs

@@ -0,0 +1,62 @@
+/**
+ * OKF v0.1 log.md formatting (knowledge-catalog okf/SPEC.md, reserved files):
+ * a `# ... Log` title, then newest-first `## YYYY-MM-DD` date headings (ISO
+ * date ONLY), each with `* **Verb**: message` bullets.
+ *
+ * Lives in src/shared (shipped in the npm package) because both the server
+ * (server/lib/okf.mjs) and the stdio MCP wiki `log` action need it —
+ * server/lib is NOT shipped to npm installs.
+ */
+
+const OKF_LOG_VERBS = ['Update', 'Creation', 'Deprecation', 'Initialization'];
+
+/** Normalize a verb: capitalized, defaulting to 'Update'. Unknown verbs pass
+ * through capitalized — the leading bold word is an OKF convention, not an
+ * enforced enum. */
+export function okfLogVerb(verb) {
+  const v = typeof verb === 'string' ? verb.trim() : '';
+  if (!v) return 'Update';
+  return v[0].toUpperCase() + v.slice(1);
+}
+
+/** One OKF log bullet: `* **Verb**: message (agent, HH:MM UTC)` */
+export function formatOkfLogEntry(verb, message, agent, when = new Date()) {
+  const hh = String(when.getUTCHours()).padStart(2, '0');
+  const mm = String(when.getUTCMinutes()).padStart(2, '0');
+  return `* **${okfLogVerb(verb)}**: ${message} (${agent}, ${hh}:${mm} UTC)`;
+}
+
+/**
+ * Insert `entryLine` under the `## YYYY-MM-DD` heading for `when` (UTC),
+ * creating the heading (newest-first, after the `# ... Log` title when one
+ * exists) if missing. Legacy `## <ISO datetime> ...` headings are left
+ * untouched — permissive, no destructive rewrite.
+ */
+export function appendOkfLogEntry(content, entryLine, when = new Date(), title = 'Log') {
+  const dateHeading = '## ' + when.toISOString().slice(0, 10);
+  const text = content || '';
+  if (!text.trim()) {
+    return ['# ' + title, '', dateHeading, '', entryLine, ''].join('\n');
+  }
+  const lines = text.split('\n');
+  const idx = lines.findIndex((l) => l.trim() === dateHeading);
+  if (idx >= 0) {
+    // Append at the end of today's section (before the next heading),
+    // skipping past trailing blank lines inside the section.
+    let end = idx + 1;
+    while (end < lines.length && !/^#{1,6}\s/.test(lines[end])) end++;
+    let insertAt = end;
+    while (insertAt > idx + 1 && lines[insertAt - 1].trim() === '') insertAt--;
+    lines.splice(insertAt, 0, entryLine);
+    return lines.join('\n');
+  }
+  // New date section goes at the top (newest first), after a leading
+  // `# ...` document title when present.
+  let at = 0;
+  if (/^#\s/.test(lines[0])) {
+    at = 1;
+    while (at < lines.length && lines[at].trim() === '') at++;
+  }
+  lines.splice(at, 0, dateHeading, '', entryLine, '');
+  return lines.join('\n');
+}

package/src/shared/record-conformance.mjs

@@ -0,0 +1,167 @@
+/**
+ * Conformance of org-defined record types.
+ *
+ * Drafted deliberately has NO built-in schema for "Process" or anything else —
+ * an org's agents invent their own vocabulary by writing typed wiki pages, and
+ * `wiki_pages.type` accepts any string. The cost of that freedom is drift: an
+ * agent declares a Process needs `steps`, then six months of writes quietly
+ * omit it, and structural queries return partial answers that LOOK complete.
+ *
+ * This is the drift report. It rejects nothing — a type definition is usually
+ * wrong on its first draft, so gating writes on one would be worse than the
+ * drift. Enforcement is opt-in per type (`enforced: true`), read by callers
+ * that choose to act on it; this module only observes.
+ *
+ * ONE reserved word: a page typed `RecordType` defines a record type. That is
+ * the single fixed point the org does not get to invent — you cannot discover
+ * definitions without agreeing on how a definition announces itself. Everything
+ * else (the type names, the field names, what they mean) belongs to the org.
+ */
+
+export const RECORD_TYPE = 'RecordType';
+
+/** How many same-typed pages before an undefined type looks like a record type
+ *  someone forgot to declare. Low enough to catch an ingest early, high enough
+ *  that a handful of Notes or Concepts never trips it. */
+export const UNDECLARED_CLUSTER_MIN = 5;
+
+function isBlank(v) {
+  if (v === null || v === undefined) return true;
+  if (typeof v === 'string') return v.trim() === '';
+  if (Array.isArray(v)) return v.length === 0;
+  if (typeof v === 'object') return Object.keys(v).length === 0;
+  return false;
+}
+
+/**
+ * Normalize a `fields` declaration. Both forms are accepted because agents
+ * write both:
+ *   fields: [owner, steps]                       -> known, not required
+ *   fields: [{ name: owner, required: true }]    -> required
+ * A bare string is deliberately NOT treated as required: shorthand should be
+ * the cheap way to sketch a type, not a way to accidentally mass-flag pages.
+ */
+export function normalizeFields(fields) {
+  if (!Array.isArray(fields)) return [];
+  const out = [];
+  for (const f of fields) {
+    if (typeof f === 'string' && f.trim()) {
+      out.push({ name: f.trim(), required: false });
+    } else if (f && typeof f === 'object' && typeof f.name === 'string' && f.name.trim()) {
+      out.push({ name: f.name.trim(), required: f.required === true });
+    }
+  }
+  return out;
+}
+
+/** The type name a definition page defines: explicit `defines`, else its title. */
+export function definedTypeName(page) {
+  const fm = (page && page.frontmatter) || {};
+  const explicit = typeof fm.defines === 'string' ? fm.defines.trim() : '';
+  if (explicit) return explicit;
+  const title = typeof page?.title === 'string' ? page.title.trim() : '';
+  return title || null;
+}
+
+/**
+ * @param pages - every wiki page for the org ({ path, title, type, frontmatter })
+ * @returns {{ types: Array, summary: object }}
+ *   types[]: { type, definedAt, enforced, fields, instances, violations[] }
+ *   violations[]: { path, missing: string[] }
+ *
+ * Only types that HAVE a definition are checked. Untyped and ad-hoc pages are
+ * none of this report's business — flagging them would bury the real drift.
+ */
+export function checkRecordConformance(pages) {
+  const all = Array.isArray(pages) ? pages : [];
+  const definitions = all.filter((p) => String(p?.type || '').trim() === RECORD_TYPE);
+
+  const types = [];
+  const seen = new Set();
+  for (const def of definitions) {
+    const typeName = definedTypeName(def);
+    if (!typeName) {
+      types.push({
+        type: null,
+        definedAt: def.path,
+        enforced: false,
+        fields: [],
+        instances: 0,
+        violations: [],
+        error: 'definition declares no type name (set frontmatter `defines`, or give the page a title)',
+      });
+      continue;
+    }
+    // Two pages defining the same type is itself drift worth surfacing —
+    // otherwise whichever sorts first silently wins.
+    if (seen.has(typeName)) {
+      types.push({
+        type: typeName,
+        definedAt: def.path,
+        enforced: false,
+        fields: [],
+        instances: 0,
+        violations: [],
+        error: 'duplicate definition for this type',
+      });
+      continue;
+    }
+    seen.add(typeName);
+
+    const fm = def.frontmatter || {};
+    const fields = normalizeFields(fm.fields);
+    const required = fields.filter((f) => f.required).map((f) => f.name);
+    const instances = all.filter((p) => String(p?.type || '').trim() === typeName);
+
+    const violations = [];
+    for (const inst of instances) {
+      const ifm = inst.frontmatter || {};
+      const missing = required.filter((name) => isBlank(ifm[name]));
+      if (missing.length) violations.push({ path: inst.path, missing });
+    }
+
+    types.push({
+      type: typeName,
+      definedAt: def.path,
+      enforced: fm.enforced === true,
+      fields,
+      instances: instances.length,
+      violations,
+    });
+  }
+
+  types.sort((a, b) => String(a.type || '').localeCompare(String(b.type || '')));
+
+  // The blind spot this closes: a report that only checks DEFINED types is
+  // silent in the most likely failure — an agent asked to "ingest all our X"
+  // writes 200 prose pages typed `Page`, defines nothing, and every number
+  // below reads zero. Health looks perfect precisely when nothing is
+  // queryable. So surface the clusters that LOOK like undeclared record types.
+  const defined = new Set(types.map((t) => t.type).filter(Boolean));
+  const counts = new Map();
+  for (const p of all) {
+    const t = String(p?.type || '').trim();
+    if (!t || t === RECORD_TYPE || defined.has(t)) continue;
+    counts.set(t, (counts.get(t) || 0) + 1);
+  }
+  const undeclared = [...counts.entries()]
+    .filter(([, n]) => n >= UNDECLARED_CLUSTER_MIN)
+    .sort((a, b) => b[1] - a[1])
+    .map(([type, pages]) => ({
+      type,
+      pages,
+      hint: `${pages} pages share type "${type}" with no RecordType definition — if these get compared or audited, define one so the fields become queryable`,
+    }));
+
+  return {
+    types,
+    undeclared,
+    summary: {
+      typesDefined: types.length,
+      instances: types.reduce((n, t) => n + t.instances, 0),
+      violations: types.reduce((n, t) => n + t.violations.length, 0),
+      definitionErrors: types.filter((t) => t.error).length,
+      undeclaredClusters: undeclared.length,
+    },
+  };
+}

package/src/shared/test-excalidraw-merge.mjs

@@ -0,0 +1,53 @@
+// Runnable self-check for mergeExcalidrawElements. No framework: `node src/shared/test-excalidraw-merge.mjs`.
+import assert from 'node:assert';
+import { mergeExcalidrawElements } from './excalidraw.mjs';
+
+const base = {
+  type: 'excalidraw', version: 2, source: 'x',
+  elements: [
+    { id: 'a', type: 'rectangle', x: 0, y: 0, strokeColor: '#000' },
+    { id: 'b', type: 'text', x: 10, y: 10, text: 'hi' },
+    { id: 'c', type: 'ellipse', x: 20, y: 20 },
+  ],
+  appState: {}, files: {},
+};
+
+// update (partial, shallow-merge keeps other props) + keeps position
+let r = mergeExcalidrawElements(base, [{ id: 'b', x: 99 }]);
+assert.deepStrictEqual(r.elements.map(e => e.id), ['a', 'b', 'c'], 'order preserved on update');
+assert.strictEqual(r.elements[1].x, 99, 'x updated');
+assert.strictEqual(r.elements[1].text, 'hi', 'other props preserved on partial update');
+
+// add appends
+r = mergeExcalidrawElements(base, [{ id: 'd', type: 'diamond', x: 5 }]);
+assert.deepStrictEqual(r.elements.map(e => e.id), ['a', 'b', 'c', 'd'], 'new element appended');
+
+// remove drops by id
+r = mergeExcalidrawElements(base, [], ['a', 'c']);
+assert.deepStrictEqual(r.elements.map(e => e.id), ['b'], 'ids removed');
+
+// remove wins over upsert of the same id
+r = mergeExcalidrawElements(base, [{ id: 'a', x: 1 }], ['a']);
+assert.deepStrictEqual(r.elements.map(e => e.id), ['b', 'c'], 'remove beats upsert');
+
+// accepts a JSON string as stored content (frame.content is a string)
+r = mergeExcalidrawElements(JSON.stringify(base), [{ id: 'e', type: 'text', x: 0 }]);
+assert.strictEqual(r.elements.length, 4, 'parses stored string content');
+
+// linear elements without points are repaired (Excalidraw crashes on restore otherwise)
+r = mergeExcalidrawElements({
+  ...base,
+  elements: [
+    { id: 'a1', type: 'arrow', x: 0, y: 0, width: 60, height: 0 },
+    { id: 'l1', type: 'line', x: 0, y: 0, width: 0, height: 0 },
+    { id: 'ok', type: 'arrow', x: 0, y: 0, width: 10, height: 10, points: [[0, 0], [10, 10]] },
+  ],
+}, []);
+assert.deepStrictEqual(r.elements[0].points, [[0, 0], [60, 0]], 'arrow points synthesized from width');
+assert.deepStrictEqual(r.elements[1].points, [[0, 0], [1, 0]], 'degenerate line gets a fallback line');
+assert.deepStrictEqual(r.elements[2].points, [[0, 0], [10, 10]], 'valid points untouched');
+
+// upsert without id is rejected
+assert.throws(() => mergeExcalidrawElements(base, [{ x: 1 }]), /must be an object with an id/);
+
+console.log('ok: mergeExcalidrawElements');

package/src/shared/wiki-excalidraw.mjs

@@ -0,0 +1,90 @@
+/**
+ * Excalidraw diagrams embedded in wiki page markdown.
+ *
+ * A diagram is a fenced block whose language is `excalidraw` and whose body is
+ * an Excalidraw scene. Keeping it inside the page (rather than as a separate
+ * frame referenced by link) means the process model and its diagram version,
+ * export and move together, and cannot drift apart.
+ *
+ * The fence pattern here MUST stay identical to the one in renderMarkdown()
+ * (server/lib/markdown.mjs) — what we find has to be exactly what renders, or
+ * an edit writes back to a block the reader never saw.
+ *
+ * Addressing: the diagram id lives INSIDE the scene JSON as `draftedDiagramId`,
+ * not in the fence info string. The shared renderer's fence regex captures the
+ * language as `\w*`, so `\`\`\`excalidraw id=d1` would not match as a fence at
+ * all and the block would stop rendering everywhere. Ordinal position was the
+ * other option and was rejected: inserting a paragraph above a diagram would
+ * silently repoint every id after it.
+ */
+
+const FENCE_RE = /```(\w*)\n([\s\S]*?)```/g;
+export const DIAGRAM_ID_KEY = 'draftedDiagramId';
+
+/** Stable-ish id for a new diagram. Callers pass an existing set to avoid collisions. */
+export function nextDiagramId(taken = new Set()) {
+  for (let n = 1; n < 10000; n++) {
+    const id = 'd' + n;
+    if (!taken.has(id)) return id;
+  }
+  throw new Error('Too many diagrams on one page');
+}
+
+/**
+ * Every excalidraw fence in the document, in order.
+ * Returns `[{ id, scene, raw, start, end }]`. A block whose body is not valid
+ * JSON is still reported (scene null) so a caller can surface it rather than
+ * silently skipping a block the reader can see.
+ */
+export function findExcalidrawBlocks(md) {
+  const text = String(md || '');
+  const out = [];
+  FENCE_RE.lastIndex = 0;
+  let m;
+  while ((m = FENCE_RE.exec(text)) !== null) {
+    if (m[1] !== 'excalidraw') continue;
+    const body = m[2];
+    let scene = null;
+    try { scene = JSON.parse(body); } catch { /* malformed — reported with scene null */ }
+    const id = scene && typeof scene[DIAGRAM_ID_KEY] === 'string' ? scene[DIAGRAM_ID_KEY] : null;
+    out.push({ id, scene, raw: body, start: m.index, end: m.index + m[0].length });
+  }
+  return out;
+}
+
+export function getExcalidrawBlock(md, diagramId) {
+  return findExcalidrawBlocks(md).find((b) => b.id === diagramId) || null;
+}
+
+/** Ids already used on this page — pass to nextDiagramId when inserting. */
+export function usedDiagramIds(md) {
+  return new Set(findExcalidrawBlocks(md).map((b) => b.id).filter(Boolean));
+}
+
+function serialize(scene, diagramId) {
+  // Id first so it survives a human hand-editing the block and is visible at a glance.
+  const { [DIAGRAM_ID_KEY]: _drop, ...rest } = scene || {};
+  return JSON.stringify({ [DIAGRAM_ID_KEY]: diagramId, ...rest }, null, 2);
+}
+
+/**
+ * Replace one diagram's scene, leaving every other byte of the page untouched.
+ * Throws when the id is absent — a save must never silently no-op or append a
+ * duplicate block the user did not ask for.
+ */
+export function replaceExcalidrawBlock(md, diagramId, scene) {
+  const text = String(md || '');
+  const block = getExcalidrawBlock(text, diagramId);
+  if (!block) throw new Error(`No excalidraw block with id "${diagramId}" on this page`);
+  const fence = '```excalidraw\n' + serialize(scene, diagramId) + '\n```';
+  return text.slice(0, block.start) + fence + text.slice(block.end);
+}
+
+/** Append a new diagram block and return `{ content, id }`. */
+export function appendExcalidrawBlock(md, scene) {
+  const text = String(md || '');
+  const id = nextDiagramId(usedDiagramIds(text));
+  const fence = '```excalidraw\n' + serialize(scene, id) + '\n```';
+  const sep = text && !text.endsWith('\n\n') ? (text.endsWith('\n') ? '\n' : '\n\n') : '';
+  return { content: text + sep + fence + '\n', id };
+}