drafted 1.17.15 → 1.17.17

package/mcp/server.mjs

@@ -129,6 +129,37 @@ export function runWithRequestState(initial, fn) {
 // Stripped from the advertised schema on remote transports.
 const LOCAL_ONLY_PARAMS = ['file_path'];
 
+/**
+ * Read a local file as UTF-8 text for a `file_path` write to /wiki or /skills.
+ *
+ * Those roots are markdown — they take `content`, not bytes — so this is a
+ * different seam from the /projects upload path, which base64s the file and
+ * sends a contentType. Without this, writing a page or a SKILL.md that already
+ * exists on disk means pasting the whole file through the caller's context,
+ * which for anything sizeable is both slow and lossy.
+ *
+ * stdio only: `file_path` is stripped from the advertised schema on remote
+ * transports (LOCAL_ONLY_PARAMS), because the server has no access to the
+ * caller's filesystem.
+ *
+ * Exported for `mcp/test-file-path-text.mjs`.
+ */
+export function textFromLocalFile(filePath) {
+  let resolved = filePath;
+  try { resolved = resolve(filePath); } catch { /* keep as-is */ }
+  if (!existsSync(resolved)) throw new Error(`file not found: ${filePath}`);
+  if (statSync(resolved).isDirectory()) {
+    throw new Error(`${filePath} is a directory — pass a file`);
+  }
+  const buf = readFileSync(resolved);
+  // A NUL byte means this is not text. Writing it would store mojibake that
+  // only shows up much later, when someone reads the page back.
+  if (buf.includes(0)) {
+    throw new Error(`${filePath} looks binary — /wiki and /skills take text (markdown)`);
+  }
+  return buf.toString('utf8');
+}
+
 // Per-tool params whose value is arbitrary / deeply-nested JSON. Zod renders
 // these (z.any(), z.array(z.any()), z.object({}).passthrough()) as an UNTYPED
 // schema — an empty `{}` or an array whose `items` has no `type`. ChatGPT's
@@ -2328,7 +2359,7 @@ 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.'),
+  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. To notify a person, put their EMAIL ADDRESS after an @ — "@sam@acme.com". A bare "@sam" only works when exactly one person on the frame has that local-part; when two do, it is ignored rather than guessed at.'),
   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.'),
@@ -2697,7 +2728,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
   to: z.string().optional().describe('[mv] destination path'),
   query: z.string().optional().describe('[search] term to match against names/content'),
   content: z.string().optional().describe('[write] inline HTML/markdown/text'),
-  file_path: z.string().optional().describe('[write] absolute path to a local file to upload (stdio only)'),
+  file_path: z.string().optional().describe('[write] absolute path to a local file to upload (stdio only). Under /projects it uploads bytes (images, PDFs, office files); under /wiki and /skills it reads the file as UTF-8 text, so a markdown file on disk can be written straight to a page or a SKILL.md without pasting it.'),
   base64: z.string().optional().describe('[write] base64-encoded binary content'),
   googleType: z.enum(['google-doc', 'google-sheet', 'google-slide']).optional().describe('[write] explicit Google Workspace type (also derived from .google-* filename extension)'),
   title: z.string().optional().describe('[write + googleType] title for a new native file'),
@@ -2808,7 +2839,11 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         return ok(page.content);
       }
       case 'write': {
-        if (!content) return err(new Error('write to /wiki/... requires content'));
+        let text = content;
+        if (text === undefined && file_path) {
+          try { text = textFromLocalFile(file_path); } catch (e) { return err(e); }
+        }
+        if (!text) return err(new Error('write to /wiki/... requires content or file_path'));
         // OKF boundary rule: /a/b.md ≡ a/b — strip a trailing .md so both spellings work.
         const canonPath = wikiPath.replace(/\.md$/, '');
         const existing = await api('GET', `/api/wiki/page?path=${encodeURIComponent(canonPath)}`, undefined, orgHeader).catch(() => null);
@@ -2817,9 +2852,9 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         // here silently forced every MCP-created page to type "Page" and a
         // path-segment title, discarding the author's frontmatter. The server
         // lifts both from the preamble and falls back to the path segment.
-        const body = { path: canonPath, content };
+        const body = { path: canonPath, content: text };
         const result = existing
-          ? await api('PUT', `/api/wiki/page?path=${encodeURIComponent(canonPath)}`, { content }, orgHeader)
+          ? await api('PUT', `/api/wiki/page?path=${encodeURIComponent(canonPath)}`, { content: text }, orgHeader)
           : await api('POST', '/api/wiki/pages', body, orgHeader);
         return ok(result || { path: canonPath, written: true });
       }
@@ -2894,7 +2929,12 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         return ok(s?.content || '');
       }
       case 'write': {
-        if (!slug || !content) return err(new Error('write /skills/<slug> requires content'));
+        if (!slug) return err(new Error('write /skills/<slug> requires a slug'));
+        let text = content;
+        if (text === undefined && file_path) {
+          try { text = textFromLocalFile(file_path); } catch (e) { return err(e); }
+        }
+        if (!text) return err(new Error('write /skills/<slug> requires content or file_path'));
         const existing = await api('GET', `/api/skills/slug/${slug}`, undefined, orgHeader).catch(() => null);
         if (!existing) {
           const g2 = g2Block(gs);
@@ -2905,8 +2945,8 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         // (the API requires a non-empty description on create).
         const description = args.description || existing?.description || `Reusable procedure: ${name.toLowerCase()}`;
         const result = existing
-          ? await api('PUT', `/api/skills/${existing.id}`, { content }, orgHeader)
-          : await api('POST', '/api/skills', { slug, name, content, description }, orgHeader);
+          ? await api('PUT', `/api/skills/${existing.id}`, { content: text }, orgHeader)
+          : await api('POST', '/api/skills', { slug, name, content: text, description }, orgHeader);
         // Writing an archived skill restores it (update flow un-archives).
         if (result?.id && existing?.archived) {
           try { await api('POST', `/api/skills/${result.id}/restore`, undefined, orgHeader); } catch { /* best-effort */ }

package/mcp/test-file-path-text.mjs

@@ -0,0 +1,58 @@
+/**
+ * Regression for textFromLocalFile() — the `file_path` text seam used by
+ * fs(write) on /wiki and /skills.
+ *
+ *   node mcp/test-file-path-text.mjs
+ *
+ * Why this exists: /projects uploads bytes (base64 + contentType), /wiki and
+ * /skills take markdown text. Routing a file down the wrong seam stores
+ * mojibake that only surfaces when someone reads the page back, so the binary
+ * guard below is the load-bearing assertion, not a nicety.
+ */
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { textFromLocalFile } from './server.mjs';
+
+const dir = mkdtempSync(join(tmpdir(), 'drafted-filepath-'));
+
+// Plain markdown round-trips byte-for-byte.
+const md = join(dir, 'page.md');
+const body = '# Title\n\nBody with a UTF-8 em dash — and an accent é.\n';
+writeFileSync(md, body, 'utf8');
+assert.equal(textFromLocalFile(md), body);
+
+// Multi-byte characters survive — a latin1 read would mangle these.
+assert.ok(textFromLocalFile(md).includes('—'));
+assert.ok(textFromLocalFile(md).includes('é'));
+
+// Empty file returns '' rather than throwing. The caller decides: both write
+// sites treat falsy text as "no content supplied" and error with guidance.
+const empty = join(dir, 'empty.md');
+writeFileSync(empty, '');
+assert.equal(textFromLocalFile(empty), '');
+
+// Binary is refused. A PNG header contains NUL bytes.
+const png = join(dir, 'shot.png');
+writeFileSync(png, Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00]));
+assert.throws(() => textFromLocalFile(png), /looks binary/);
+
+// Directories are refused with a clear message, not an EISDIR stack trace.
+const sub = join(dir, 'nested');
+mkdirSync(sub);
+assert.throws(() => textFromLocalFile(sub), /is a directory/);
+
+// Missing files name the path the caller passed, not the resolved one.
+assert.throws(() => textFromLocalFile(join(dir, 'nope.md')), /file not found/);
+
+// Relative paths resolve against cwd rather than being read blindly.
+assert.throws(() => textFromLocalFile('definitely-not-here-xyz.md'), /file not found/);
+
+console.log('file_path text seam ok — utf8 preserved, binary and dirs refused');
+
+// Importing server.mjs opens the MCP WebSocket at module scope, which pins the
+// event loop open forever. mcp/test-org-guards.mjs only exits because it
+// finishes in ~176ms — before the socket connects — so it passes on a race
+// rather than by design. Exit explicitly instead of inheriting that luck.
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.17.15",
+  "version": "1.17.17",
   "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": [
@@ -72,7 +72,7 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "sharp": "^0.34.5",
-    "ws": "^8.16.0",
+    "ws": "^8.21.3",
     "yaml": "^2.8.3",
     "zod": "^4.3.6"
   },