drafted 1.18.4 → 1.19.0

package/mcp/server.mjs

@@ -291,6 +291,33 @@ export function matchesAllTerms(parts, query) {
   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);
@@ -2774,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'),
@@ -2824,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
@@ -3108,11 +3194,13 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
       if (!q) return err(new Error('search requires a query — e.g. fs(search, path="/projects", query="<terms>")'));
       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.
@@ -3127,18 +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, and frame search matches LABELS only — so a term that lives in
-        // frame content is a miss, not an absence.
-        out.push(`\nNo frame label matches "${q}" (frame search matches labels, not frame content).`);
+        // 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'));
     }
@@ -3346,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}" (frame search matches labels, not frame content).`);
-          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

@@ -6,7 +6,7 @@
 // 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 } from './server.mjs';
+import { matchesAllTerms, formatFrameHits, archivedNote, clip } from './server.mjs';
 
 const proj = [
   'Flow AI MCP Server Feature Card',
@@ -38,5 +38,42 @@ assert.equal(matchesAllTerms(proj, undefined), false);
 assert.equal(matchesAllTerms([null, undefined, 'alpha'], 'alpha'), true);
 assert.equal(matchesAllTerms([null, undefined, 'alpha'], 'null'), false);
 
-console.log('search term matching ok — every term must hit, across fields, never vacuously');
+// ── 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.4",
+  "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": [