drafted 1.18.3 → 1.19.0

package/mcp/server.mjs

@@ -279,6 +279,45 @@ export function stripUrlOrigin(p) {
 // segment 0, so `write /skills/<slug>/README.md` silently rewrote SKILL.md — and
 // the create-time README gate then looked unsatisfiable from this tool.
 // Pure + exported (asserted in mcp/test-skill-paths.mjs).
+// Search matches every TERM in the query, not the raw phrase. A whole-string
+// substring test means a natural multi-word search ("tool surface parity MCP")
+// never hits a project whose name/slug/description contains each of those words
+// — while the single word "parity" does. That reads as "no such project" for a
+// project that is right there. Pure + exported (asserted in mcp/test-search-terms.mjs).
+export function matchesAllTerms(parts, query) {
+  const terms = String(query || '').toLowerCase().split(/\s+/).filter(Boolean);
+  if (!terms.length) return false;
+  const hay = parts.map((v) => String(v || '')).join(' ').toLowerCase();
+  return terms.every((t) => hay.includes(t));
+}
+
+// One frame hit: its addressable path, and the line that matched underneath it.
+// A hit with no snippet matched on the LABEL, not on content — say which, so the
+// agent knows whether the frame's text is evidence or just its filename.
+// Pure + exported (asserted in mcp/test-search-terms.mjs).
+export function formatFrameHits(frames, { limit = 25, snippetChars = 200 } = {}) {
+  return frames.slice(0, limit).map((f) => {
+    const path = `/o/${f.orgSlug || f.orgId}/projects/${f.projectSlug || f.projectId}/${f.layer}/${f.lane || ''}/${f.label}`.replace(/\/\//g, '/');
+    const snip = clip(String(f.snippet || '').replace(/\s+/g, ' ').trim(), snippetChars);
+    return snip ? `  ${path}\n      ${snip}` : `  ${path}  (label match)`;
+  }).join('\n');
+}
+
+// A search result is a POINTER. Long fields (a skill's full description, a
+// paragraph-length snippet) turn a 25-hit answer into a payload the client spills
+// to a file — the failure that made the old /projects listing unusable in-band.
+export function clip(s, n) {
+  const t = String(s || '').trim();
+  return t.length > n ? t.slice(0, n - 1).trimEnd() + '…' : t;
+}
+
+// Archived projects are excluded from search results, mirroring the web UI. Saying
+// how many were withheld is the difference between a scoped answer and a silent
+// omission — the failure that prompted docs/plans/frame-content-search.md.
+export function archivedNote(n) {
+  return n > 0 ? `\n(${n} more in archived projects — not listed; move the project out of Archive to surface them)` : '';
+}
+
 export function splitSkillPath(p) {
   const rest = /^\/skills\/?$/.test(p || '') ? '' : String(p || '').replace(/^\/skills\/?/, '');
   const segs = rest.split('/').filter(Boolean);
@@ -2762,7 +2801,7 @@ server.resource('info', 'drafted://info', {
   };
 });
 
-tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder: `fs(ls, path="/")` lists the orgs you can address, then `/o/<org>/<root>/...` addresses one of them — the org is part of the path, there is no org switching:\n\n- `/o/<org>/wiki/<path>` — org knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `/o/<org>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside)\n- `/o/<org>/projects/<folder?>/<project>/<layer>/<lane>/<file>` — producible frames (folder optional; then exactly layer → lane → file)\n\n(Bare `/wiki`, `/skills`, `/projects` roots still resolve via the session\'s working org.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move, cross-project), `rm` (delete), `search` (across wiki + skills + projects). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, attached-skill gates fire on mutations, anchored frames must be read before editing a layer, `.skillinstall/` is stripped on skill push.', {
+tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder: `fs(ls, path="/")` lists the orgs you can address, then `/o/<org>/<root>/...` addresses one of them — the org is part of the path, there is no org switching:\n\n- `/o/<org>/wiki/<path>` — org knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `/o/<org>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside)\n- `/o/<org>/projects/<folder?>/<project>/<layer>/<lane>/<file>` — producible frames (folder optional; then exactly layer → lane → file)\n\n(Bare `/wiki`, `/skills`, `/projects` roots still resolve via the session\'s working org.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move, cross-project), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/")` or `path="/o/<org>"` fans out across wiki + skills + projects in one call). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, attached-skill gates fire on mutations, anchored frames must be read before editing a layer, `.skillinstall/` is stripped on skill push.', {
   action: z.enum(['ls', 'read', 'write', 'edit', 'mv', 'rm', 'mkdir', 'search']).describe('Filesystem verb.'),
   path: z.string().describe('Drafted path: /o/<org>/wiki/... | /o/<org>/skills/... | /o/<org>/projects/... (bare /wiki, /skills, /projects also work; for mv: source)'),
   to: z.string().optional().describe('[mv] destination path'),
@@ -2812,6 +2851,65 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
 
   // ── Root listing: / or empty → the orgs this session can address (Shape A) ──
   if (!p || p === '/' || p === '') {
+    // search at the root fans out across all three roots, so the tool description's
+    // "search across wiki + skills + projects" is literally one call. Each leg is
+    // capped and labelled: the point is to find WHERE something lives, not to dump
+    // three inventories. A leg that fails says so instead of reading as zero hits.
+    if (action === 'search') {
+      const q = String(query || '').trim();
+      if (!q) return err(new Error('search requires a query — e.g. fs(search, path="/", query="<terms>")'));
+      const scope = orgFromPath ? `/o/${orgFromPath}` : '';
+      const leg = async (fn) => { try { return { v: await fn() }; } catch (e) { return { e: e?.message || String(e) }; } };
+      const [wiki, skills, projects, frames] = await Promise.all([
+        leg(() => api('GET', `/api/wiki/search?q=${encodeURIComponent(q)}&limit=10`, undefined, orgHeader)),
+        leg(() => api('GET', `/api/skills/search?q=${encodeURIComponent(q)}`, undefined, orgHeader)),
+        leg(() => api('GET', '/api/projects', undefined, orgHeader)),
+        leg(() => withoutProjectScope(() => api('GET', `/api/search?q=${encodeURIComponent(q)}&limit=15`))),
+      ]);
+      // A root search IS the prior-art search both gates ask for — it read the wiki
+      // and the skill library. Not crediting it would send the agent back to run
+      // the same two queries again.
+      markSearched(gs, 'wiki');
+      markSearched(gs, 'skill');
+
+      const out = [];
+      const section = (title, res, render) => {
+        if (res.e) { out.push(`${title}: unavailable (${res.e})`); return; }
+        const body = render(res.v);
+        out.push(body ? `${title}:\n${body}` : `${title}: no matches`);
+      };
+
+      section('Wiki', wiki, (v) => {
+        const hits = (v?.hits || v?.pages || v?.results || []).slice(0, 10);
+        return hits.length ? hits.map(h => `  ${scope}/wiki/${h.path}${h.title ? `  — ${clip(h.title, 80)}` : ''}`).join('\n') : '';
+      });
+      section('Skills', skills, (v) => {
+        // Fewer than the other legs on purpose: skills search is fuzzy and its tail
+        // is weak matches, which is noise in a fan-out whose job is "where does this
+        // live?". fs(search, path="/skills") is the place to go deeper.
+        const list = (Array.isArray(v) ? v : (v?.skills || [])).slice(0, 5);
+        return list.length ? list.map(s => `  ${scope}/skills/${s.slug}  — ${clip(s.description || s.name, 120)}`.trimEnd()).join('\n') : '';
+      });
+
+      let allowed = null;
+      section('Projects', projects, (v) => {
+        let rows = (Array.isArray(v?.projects) ? v.projects : []).filter(x => x.folder !== '__archived');
+        if (orgFromPath) rows = rows.filter(x => x.orgSlug === orgFromPath || x.orgId === orgFromPath);
+        allowed = new Set(rows.map(x => x.id));
+        const hits = rows.filter(x => matchesAllTerms([x.name, x.slug, x.description], q)).slice(0, 10);
+        return hits.length ? hits.map(x => `  /o/${x.orgSlug || x.orgId}/projects/${x.slug || x.id}`).join('\n') : '';
+      });
+      section('Frames', frames, (v) => {
+        let hits = Array.isArray(v) ? v : (v?.results || []);
+        // Only gate on org when the projects leg actually resolved; an empty set
+        // from a FAILED projects call would silently zero out every frame hit.
+        if (orgFromPath && allowed) hits = hits.filter(f => allowed.has(f.projectId));
+        const note = archivedNote(Array.isArray(v) ? 0 : (v?.archivedCount || 0));
+        return hits.length ? formatFrameHits(hits, { limit: 15 }) + note : (note ? note.trimStart() : '');
+      });
+
+      return ok(`Search "${q}"${orgFromPath ? ` in /o/${orgFromPath}` : ''}\n\n${out.join('\n\n')}`);
+    }
     if (action !== 'ls') return err(new Error('read/write/edit/mv/rm require a path under /o/<org>/wiki, /o/<org>/skills, or /o/<org>/projects'));
     if (orgFromPath) {
       // ls /o/<org> → that org's three roots
@@ -3094,16 +3192,15 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
       // addressable paths instead of the whole inventory.
       const q = String(query || '').trim();
       if (!q) return err(new Error('search requires a query — e.g. fs(search, path="/projects", query="<terms>")'));
-      const needle = q.toLowerCase();
-      const hitProjects = rows.filter(x =>
-        [x.name, x.slug, x.description].some(v => String(v || '').toLowerCase().includes(needle))
-      );
+      const hitProjects = rows.filter(x => matchesAllTerms([x.name, x.slug, x.description], q));
       let frames = [];
+      let archivedCount = 0;
       let frameError = null;
       try {
         // Unscoped: this is the org-wide "does anything for X exist?" question.
         const res = await withoutProjectScope(() => api('GET', `/api/search?q=${encodeURIComponent(q)}`));
         frames = Array.isArray(res) ? res : (res?.results || []);
+        archivedCount = Array.isArray(res) ? 0 : (res?.archivedCount || 0);
       } catch (e) {
         // Project matches still answer "does this exist?", so don't fail the whole
         // call — but say the frame leg broke rather than implying zero hits.
@@ -3118,12 +3215,13 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         ? `Projects matching "${q}":\n${formatProjectIndex(hitProjects, { boundPath })}`
         : `No project name or description matches "${q}".`);
       if (frames.length) {
-        const lines = frames.slice(0, 25).map(f =>
-          `  /o/${f.orgSlug || f.orgId}/projects/${f.projectSlug || f.projectId}/${f.layer}/${f.lane || ''}/${f.label}`.replace(/\/\//g, '/')
-        );
-        out.push(`\nFrames matching "${q}" (${frames.length}${frames.length > 25 ? ', first 25' : ''}):\n${lines.join('\n')}`);
+        out.push(`\nFrames matching "${q}" (${frames.length}${frames.length > 25 ? ', first 25' : ''}):\n${formatFrameHits(frames)}${archivedNote(archivedCount)}`);
       } else if (frameError) {
         out.push(`\n(frame search unavailable: ${frameError} — project matches above are complete, frame matches were not checked)`);
+      } else {
+        // Say the frame leg ran and found nothing. Printing only the project leg
+        // leaves "frames were never searched" and "no frame matched" looking the same.
+        out.push(`\nNo frame matches "${q}" (searched frame labels and content).${archivedNote(archivedCount)}`);
       }
       return ok(out.join('\n'));
     }
@@ -3331,11 +3429,9 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
           // Express parse projectId as an ARRAY and the scope match nothing.
           const res = await api('GET', `/api/search?q=${encodeURIComponent(q)}`);
           const frames = Array.isArray(res) ? res : (res?.results || []);
-          if (!frames.length) return ok(`No frames matching "${q}".`);
-          const lines = frames.slice(0, 50).map(f =>
-            `  /o/${f.orgSlug || f.orgId}/projects/${f.projectSlug || f.projectId}/${f.layer}/${f.lane || ''}/${f.label}`.replace(/\/\//g, '/')
-          );
-          return ok(`${frames.length} frame${frames.length === 1 ? '' : 's'} matching "${q}":\n${lines.join('\n')}`);
+          const archivedCount = Array.isArray(res) ? 0 : (res?.archivedCount || 0);
+          if (!frames.length) return ok(`No frames matching "${q}" (searched frame labels and content).${archivedNote(archivedCount)}`);
+          return ok(`${frames.length} frame${frames.length === 1 ? '' : 's'} matching "${q}":\n${formatFrameHits(frames, { limit: 50 })}${archivedNote(archivedCount)}`);
         }
         default:
           return err(new Error(`fs ${action} not supported for /projects`));

package/mcp/test-search-terms.mjs

@@ -0,0 +1,79 @@
+// Regression for fs(search) term matching on /projects.
+// Run: `node mcp/test-search-terms.mjs`. No framework — asserts the pure core.
+//
+// Why this exists: search used to substring-test the WHOLE query against each
+// field, so `query="tool surface parity MCP Flow"` missed a project whose
+// description says "tool surface" and "parity" — while `query="parity"` hit it.
+// An agent reads that miss as "the project does not exist" and stops looking.
+import assert from 'node:assert/strict';
+import { matchesAllTerms, formatFrameHits, archivedNote, clip } from './server.mjs';
+
+const proj = [
+  'Flow AI MCP Server Feature Card',
+  'flow-ai-mcp-server-feature-card',
+  'Covers the BEO-2527 parity guard for the agent tool surface.',
+];
+
+// The reported failure: a natural multi-word query spanning name AND description.
+assert.equal(matchesAllTerms(proj, 'tool surface parity MCP Flow'), true);
+// The single word that did work must keep working.
+assert.equal(matchesAllTerms(proj, 'parity'), true);
+// Terms match across fields and across a hyphenated slug.
+assert.equal(matchesAllTerms(proj, 'flow feature card'), true);
+assert.equal(matchesAllTerms(proj, 'BEO-2527'), true);
+// Case and surrounding whitespace are irrelevant.
+assert.equal(matchesAllTerms(proj, '  PARITY   Guard '), true);
+
+// AND, not OR: one unmatched term is a miss. An OR would return most of the org.
+assert.equal(matchesAllTerms(proj, 'parity kubernetes'), false);
+assert.equal(matchesAllTerms(proj, 'kubernetes'), false);
+
+// An empty query never matches — the caller rejects it before this, and
+// "every term" over zero terms would otherwise be vacuously true for every row.
+assert.equal(matchesAllTerms(proj, ''), false);
+assert.equal(matchesAllTerms(proj, '   '), false);
+assert.equal(matchesAllTerms(proj, undefined), false);
+
+// Null/undefined fields don't throw or match a stray "null"/"undefined" term.
+assert.equal(matchesAllTerms([null, undefined, 'alpha'], 'alpha'), true);
+assert.equal(matchesAllTerms([null, undefined, 'alpha'], 'null'), false);
+
+// ── Frame hit rendering (docs/plans/frame-content-search.md, Phase 2) ────────
+const hit = {
+  orgSlug: 'beoflow', projectSlug: 'flow-ai-mcp-server-feature-card',
+  layer: 'plans', lane: 'phase-0', label: 'feature-plan.md',
+  snippet: 'the BEO-2527 «parity guard» runs\n  before every diff',
+};
+const rendered = formatFrameHits([hit]);
+assert.match(rendered, /\/o\/beoflow\/projects\/flow-ai-mcp-server-feature-card\/plans\/phase-0\/feature-plan\.md/);
+// The snippet is the evidence — it must survive, with its newlines flattened so
+// one hit stays one block instead of wrapping into the next path.
+assert.match(rendered, /«parity guard» runs before every diff/);
+assert.equal(rendered.split('\n').length, 2);
+
+// A hit with no snippet matched the LABEL, not content. Say so rather than
+// rendering a bare path that looks identical to a content match.
+assert.match(formatFrameHits([{ ...hit, snippet: null }]), /\(label match\)$/);
+assert.match(formatFrameHits([{ ...hit, snippet: '   ' }]), /\(label match\)$/);
+
+// A lane-less frame must not render a doubled slash — that path is not addressable.
+assert.ok(!formatFrameHits([{ ...hit, lane: null }]).includes('//'));
+
+// The cap is a cap; nothing renders beyond it.
+assert.equal(formatFrameHits(Array(40).fill({ ...hit, snippet: null }), { limit: 3 }).split('\n').length, 3);
+
+// Archived matches are counted, never silently dropped — and zero says nothing.
+assert.equal(archivedNote(0), '');
+assert.match(archivedNote(2), /2 more in archived projects/);
+
+// A result is a pointer, not the document: long fields are clipped so 25 hits
+// stay readable in-band instead of spilling to a file.
+assert.equal(clip('short', 20), 'short');
+assert.equal(clip('x'.repeat(50), 20).length, 20);
+assert.match(clip('x'.repeat(50), 20), /…$/);
+assert.equal(clip(null, 20), '');
+const long = formatFrameHits([{ ...hit, snippet: 'w '.repeat(400) }], { snippetChars: 60 });
+assert.ok(long.split('\n')[1].length <= 60 + 6, 'snippet line stays within its cap + indent');
+
+console.log('search term matching + frame hit rendering ok');
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.18.3",
+  "version": "1.19.0",
   "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": [