drafted 1.17.12 → 1.17.14

package/mcp/server.mjs

@@ -307,8 +307,12 @@ const TOOL_ANNOTATIONS = {
   // name describing the work before any other tool call succeeds.
   session:             { title: 'Session',              readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Name THIS agent session (and rename it later). The name is what the user sees on your surface tab — pick a short 2-3 word description of the work (e.g. "beoflow backend", "drafted fs work"). The name persists across reconnects and restarts; you only set it once unless the work changes. Dispatch by `action`: `name` (set/rename with the `name` param).' },
 
+  // Comments — the review loop agents could previously only reach over raw HTTP
+  comment:             { title: 'Comments',              readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Read and write review comments on frames. Comments are notes ABOUT THE WORK: they attach to a frame, optionally to one element inside it, and anyone who can see the frame sees them. Dispatch by `action`: list (paginated, compact mode), add (with an optional element anchor or a reply), resolve, reopen, delete. Use this to leave findings a human can action in place, and to read the feedback they left you.' },
+
   // Canvas / view
   focus:               { title: 'Focus on target',     readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Pan the canvas viewport for connected clients to a frame, lane, or layer.' },
+  tour:                { title: 'Guided tours',        readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Play or stop an agent-authored guided tour (driver.js) on the project surface for all connected clients. Tours live on a frame\'s metadata.tour — author them with fs(write, metadata={tour: {title, steps}}). Dispatch by `action`: play (frameId) starts the walkthrough, stop (projectId) ends it. Use for presentations and collaborative walkthroughs.' },
   screenshot:          { title: 'Screenshot',          readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'Render a PNG via headless browser. `scope=frame` for a single frame, `scope=canvas` for a region of the project surface.' },
 
   // Minions — checklist-driven intake surfaces bound to a project
@@ -418,7 +422,7 @@ function tool(name, descOrSchema, schemaOrHandler, handler) {
           const v = args[0][k];
           if (typeof v === 'string' && v.trim()) {
             try { args[0][k] = JSON.parse(v); }
-            catch { return err(new Error(`Param "${k}" must be a JSON-encoded ${['excalidraw_data', 'frontmatter', 'target', 'output', 'state'].includes(k) ? 'object' : 'array'} string; JSON.parse failed.`)); }
+            catch { return err(new Error(`Param "${k}" must be a JSON-encoded ${['excalidraw_data', 'frontmatter', 'target', 'output', 'state', 'metadata'].includes(k) ? 'object' : 'array'} string; JSON.parse failed.`)); }
           }
         }
       }
@@ -2299,6 +2303,122 @@ tool('trigger', {
   } catch (error) { return err(error); }
 });
 
+tool('tour', {
+  action: z.enum(['play', 'stop']).describe('play: start a guided tour on the project surface for all connected clients. stop: end the currently playing tour.'),
+  frameId: z.string().optional().describe('[play] Tour frame: a frame path (/projects/<project>/<layer>/<lane>/<file>), frame URL, or frame UUID. The frame must carry metadata.tour (steps: [{target, title?, body?, side?, advanceOnClick?}]).'),
+  projectId: z.string().optional().describe('[stop] Project UUID or slug owning the tour.'),
+}, async ({ action, frameId, projectId }) => {
+  try {
+    if (action === 'play') {
+      if (!frameId) throw new Error('frameId is required for tour play');
+      const { frameId: fid } = await resolveFsFramePath(frameId);
+      const result = await api('POST', '/api/tour/play', { frameId: fid });
+      return ok(result);
+    }
+    if (action === 'stop') {
+      if (!projectId) throw new Error('projectId is required for tour stop');
+      const result = await api('POST', '/api/tour/stop', { projectId });
+      return ok(result);
+    }
+    throw new Error(`Unknown tour action: ${action}`);
+  } catch (error) { return err(error); }
+});
+
+tool('comment', {
+  action: z.enum(['list', 'add', 'resolve', 'reopen', 'delete']).describe('list: read comments (paginated). add: post a comment or a reply. resolve/reopen: flip a comment\'s state. delete: remove one.'),
+  target: z.string().optional().describe('[list, add] The frame: a path (/projects/<project>/<layer>/<lane>/<file>), a frame URL, or a frame UUID. Required for add. For list, omit it to read the whole project.'),
+  projectId: z.string().optional().describe('[list] Project to read when no target is given — UUID, slug, or /projects/<name>. Defaults to the session\'s bound project.'),
+  body: z.string().optional().describe('[add] The comment text. Be specific and actionable: quote what you mean and say what should change. Prefix with [MUST] / [NICE] / [Q] so a reviewer can triage.'),
+  replyTo: z.string().optional().describe('[add] Comment UUID this replies to. A reply cannot carry its own anchor — it inherits the thread\'s.'),
+  anchorRef: z.string().optional().describe('[add] CSS selector for the element this comment is about, e.g. "h1" or ".email-body > p:nth-of-type(3)". The frame must load /vendor/frame-guide.js (markdown and HTML content frames get it automatically). Without it the comment lands on the whole frame.'),
+  anchorText: z.string().optional().describe('[add] The text of the anchored element, stored as a snapshot. Supply it whenever you pass anchorRef: a selector is an nth-of-type path that breaks when the frame is re-authored, and this snapshot is the only way to re-find what you meant.'),
+  commentId: z.string().optional().describe('[resolve, reopen, delete] The comment UUID.'),
+  status: z.enum(['open', 'resolved', 'all']).optional().describe('[list] Filter. Defaults to open — the comments that still need action.'),
+  limit: z.number().optional().describe('[list] Max comments to return (default 25).'),
+  offset: z.number().optional().describe('[list] Skip this many before returning (default 0).'),
+  compact: z.boolean().optional().describe('[list] Return only id, frame, author, status and a truncated body — enough to pick one to act on, without the full text of every thread.'),
+}, async ({ action, target, projectId, body, replyTo, anchorRef, anchorText, commentId, status, limit, offset, compact }) => {
+  try {
+    if (action === 'add') {
+      if (!target) throw new Error('target is required for comment add');
+      if (!body || !String(body).trim()) throw new Error('body is required for comment add');
+      const { frameId } = await resolveFsFramePath(target);
+      // A reply inherits its parent's anchor; sending both would silently drop one.
+      const anchor = (!replyTo && anchorRef)
+        ? { type: 'selector', ref: anchorRef, ...(anchorText ? { text: anchorText } : {}) }
+        : null;
+      const result = await api('POST', `/api/frames/${frameId}/comments`, {
+        body: String(body),
+        parentId: replyTo || null,
+        anchor,
+      });
+      return ok(result);
+    }
+    if (action === 'resolve' || action === 'reopen') {
+      if (!commentId) throw new Error(`commentId is required for comment ${action}`);
+      const result = await api('PATCH', `/api/comments/${commentId}`, { resolved: action === 'resolve' });
+      return ok(result);
+    }
+    if (action === 'delete') {
+      if (!commentId) throw new Error('commentId is required for comment delete');
+      // DELETE answers 204 with an empty body, so there is nothing to echo back.
+      await api('DELETE', `/api/comments/${commentId}`);
+      return ok({ deleted: commentId });
+    }
+    if (action === 'list') {
+      let rows;
+      let scope;
+      if (target) {
+        // /api/frames/:id/comments does not join designs, so its rows carry no frameLabel.
+        // Name the frame once in the scope instead of emitting `frame: null` on every row.
+        const { frameId } = await resolveFsFramePath(target);
+        rows = (await api('GET', `/api/frames/${frameId}/comments`)).comments || [];
+        scope = { frameId, frame: target };
+      } else {
+        const meta = await resolveProjectArg(projectId || getState().projectId, { required: true });
+        rows = (await api('GET', `/api/projects/${meta.id}/comments`)).comments || [];
+        scope = { projectId: meta.id, project: meta.name };
+      }
+      const want = status || 'open';
+      const filtered = rows.filter((c) => (want === 'all' ? true : want === 'resolved' ? !!c.resolvedAt : !c.resolvedAt));
+      const total = filtered.length;
+      const start = Math.max(0, Number(offset) || 0);
+      const size = Math.max(1, Math.min(Number(limit) || 25, 200));
+      const page = filtered.slice(start, start + size);
+      const shape = (c) => compact
+        ? {
+            id: c.id,
+            ...(c.frameLabel ? { frame: c.frameLabel } : {}),
+            author: c.authorName || c.authorEmail || null,
+            status: c.resolvedAt ? 'resolved' : 'open',
+            replyTo: c.parentId || null,
+            body: String(c.body || '').slice(0, 120),
+          }
+        : {
+            id: c.id,
+            frameId: c.frameId,
+            ...(c.frameLabel ? { frame: c.frameLabel, layer: c.layer || null, lane: c.lane || null } : {}),
+            author: c.authorName || c.authorEmail || null,
+            status: c.resolvedAt ? 'resolved' : 'open',
+            replyTo: c.parentId || null,
+            anchor: c.anchor || null,
+            body: c.body,
+            createdAt: c.createdAt,
+          };
+      return ok({
+        ...scope,
+        status: want,
+        comments: page.map(shape),
+        totalAvailable: total,
+        returned: page.length,
+        truncated: start + page.length < total,
+        ...(start + page.length < total ? { nextOffset: start + page.length } : {}),
+      });
+    }
+    throw new Error(`Unknown comment action: ${action}`);
+  } catch (error) { return err(error); }
+});
+
 tool('focus', {
   target: z.string().describe('What to pan the canvas to: a frame path (/projects/<project>/<layer>/<lane>/<file>), a frame URL (any URL containing /f/{uuid} or /o/<org>/projects/...), or a frame ID (UUID). When a user shares a Drafted link, pass it directly here.'),
 }, async ({ target }) => {
@@ -2565,7 +2685,7 @@ server.resource('info', 'drafted://info', {
           skills: '/o/<org>/skills/<slug>',
           projects: '/o/<org>/projects/<folder?>/<project>/<layer>/<lane>/<file>',
         },
-        tools: ['fs (ls/read/write/edit/mv/rm/mkdir/search)', 'whoami', 'auth', 'session', 'trigger', 'focus', 'screenshot', 'minion'],
+        tools: ['fs (ls/read/write/edit/mv/rm/mkdir/search)', 'whoami', 'auth', 'session', 'trigger', 'focus', 'tour', 'screenshot', 'minion'],
       }, null, 2),
     }],
   };
@@ -2583,13 +2703,14 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
   title: z.string().optional().describe('[write + googleType] title for a new native file'),
   ops: z.array(z.any()).optional().describe('[edit] hashline ops for text frames. Apply ONLY against a fresh fs(read) of the frame: each op = {type, lineHash, newContent} where type is one of replace | delete | insertAfter | insertBefore, and lineHash is the FULL anchor from the read output (line number + hash, e.g. the token left of the |, like 42srt) — NOT a bare hash. delete/replace consume the target line; at most one replace/delete per line per edit (combine into one replace). If an op targets a line that changed since read it is rejected — re-read and retry. Element ops for excalidraw ({id,x,y,...}), or structured ops for office'),
   state: z.any().optional().describe('[write] app-frame state (JSON) to persist for a deployed windowType:"app" frame; the canvas hydrates the app from it on load. Max 64KB.'),
+  metadata: z.any().optional().describe('[write] JSON metadata to attach to the written frame (e.g. {"tour": {title, auto?, steps}} to define a guided tour on this frame). Max 64KB.'),
   recursive: z.boolean().optional().describe('[ls] recurse into subdirectories'),
   lines: z.string().optional().describe('[read] line range (e.g. "1-50") — partial read; content is hashline-annotated so a later edit stays surgical'),
   pattern: z.string().optional().describe('[ls] filter filenames (e.g. "*.html")'),
   org: z.string().optional().describe('Org (id or name) for bare /wiki and /skills paths (org-scoped /o/<org>/... paths don\'t need it). Per-request only; project paths self-derive org from the project row.'),
   projectId: PROJECT_OVERRIDE_PARAM,
 }, async (args) => {
-  const { action, path: rawPath, to: rawTo, query, content, file_path, base64, googleType, title, ops, state, recursive, pattern, lines, org } = args;
+  const { action, path: rawPath, to: rawTo, query, content, file_path, base64, googleType, title, ops, state, metadata, recursive, pattern, lines, org } = args;
   // Org-scoped path (Shape A): /o/<org>/<root>/... — strip the org segment here,
   // carry it as the per-request org scope (orgHeader), validate per-root below.
   // The PATH is the address; the org= param is legacy for bare roots only, and a
@@ -2969,6 +3090,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
           }
           else if (base64) body.base64 = base64;
           else return err(new Error('write requires one of content / file_path / base64 / googleType / state'));
+          if (metadata !== undefined) body.metadata = metadata;
           const result = await api('PUT', `/api/fs/${filePath}`, body, orgHeader);
           if (state !== undefined && result?.id) {
             try { await api('POST', `/api/file/${result.id}/state`, { state }); } catch { /* state best-effort */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.17.12",
+  "version": "1.17.14",
   "description": "Drafted — visual thinking surface for humans and AI agents. Renders HTML, markdown, images, and code as frames on a zoomable canvas, with MCP tools for AI agents and real-time sync for humans.",
   "type": "module",
   "files": [
@@ -64,6 +64,7 @@
     "mdast-util-from-markdown": "^2.0.3",
     "multer": "^2.1.1",
     "nodemailer": "^8.0.2",
+    "parse5": "^8.0.1",
     "pg": "^8.20.0",
     "playwright": "^1.58.2",
     "puppeteer": "^24.37.5",

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/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 };
+}