@yojahny/wp-design-library 1.1.1 → 1.3.0

package/src/mcp/prompts.mjs

@@ -23,24 +23,31 @@ session did not make.
 
 ## Order of operations
 
-1. **Arguments.** \`path\` must exist; pass it as an absolute path. Animated webp and gif
-   always work; video (mp4/mov/webm/mkv) needs ffmpeg on the server's PATH. If \`add\`
-   returns \`refused\` starting with \`ffmpeg\`, relay the message and stop. \`source\` is
+1. **Arguments.** \`input\` may be a live HTTP(S) page or an animated webp/gif/video
+   (mp4/mov/webm/mkv). A local file uses an absolute path. Video needs ffmpeg on the
+   server's PATH. If \`add\` returns \`refused\` starting with \`ffmpeg\`, relay the
+   message and stop. \`source\` is
    one of ${list(v.source)}. Derive \`slug\` from the file name when absent (lowercase,
    dashes, no extension) and confirm it with the user; derive \`title\` from the slug and
    confirm. \`url\` must be a full URL with scheme. \`license\` defaults by kind: own →
    "own work"; open → ask for the licence name; paid and public-site → "description
    only, no redistribution of the source".
-2. **Ingest.** Call the \`add\` tool with those values. If it returns \`refused\` because
+2. **Stage when hosted.** A hosted server cannot read a path on the caller's machine.
+   Upload it first with \`LIBRARY_TOKEN\` configured locally: \`library upload
+   <absolute-path> --server <server-origin> --source <kind> --license "<licence>"
+   [--url <source-url>] [--title <title>]\`. Use returned \`file\` name as the \`add\`
+   input; hosted MCP resolves a bare name inside its inbox. Never print or pass the token as an argument.
+   Live page URLs need no upload.
+3. **Ingest.** Call the \`add\` tool with those values. If it returns \`refused\` because
    the slug exists, ask before calling again with \`force: true\`; a forced re-add resets
    the draft. Over a hosted (HTTP) server \`add\` can only read files already in the server's
    inbox; if the refusal mentions \`inbox\`, say so and stop.
-3. **Read.** Open the returned \`strip\`. Read \`media.duration_ms\` from the draft at
+4. **Read.** Open the returned \`strip\`. Read \`media.duration_ms\` from the draft at
    \`<dir>/entry.md\`; if it is above 10000, call \`add\` again with \`force: true\` and
    \`frames: 36\` before tagging. The server caps at 36 frames; beyond about 18 seconds a
    section can still be missed, so build a denser sheet yourself from the source file
    before writing the motion note.
-4. **Tag.** Fill every field in the returned \`blanks\` list, per the rubric below. Write
+5. **Tag.** Fill every field in the returned \`blanks\` list, per the rubric below. Write
    the motion note last, after the roster. Two ways, same result: call \`set_fields\` with
    those field names — this needs **no filesystem** and is the only way that works against
    a hosted server — or, in a local checkout, edit \`<dir>/entry.md\` directly.
@@ -48,11 +55,11 @@ session did not make.
    anything, so a refusal never leaves a half-filled draft. It writes judgement fields
    only; provenance is refused. \`get_vocab\` returns the terms if you did not read them
    above.
-5. **Approve.** Show the draft to the user and **show the draft and wait for a yes** before
+6. **Approve.** Show the draft to the user and **show the draft and wait for a yes** before
    anything else. Apply their edits.
-6. **Save.** Call \`save_entry\`. On \`refused\`, show the field names, fix, and call again;
+7. **Save.** Call \`save_entry\`. On \`refused\`, show the field names, fix, and call again;
    **never remove a field to make it pass**.
-7. **Offer the git step.** The library checkout is the directory that contains the
+8. **Offer the git step.** The library checkout is the directory that contains the
    \`bin/library.mjs\` this server runs; if that is not a git checkout (the \`npx\` case), ask
    the user for the path to their clone. If the \`dir\` returned by \`add\` is not inside the
    checkout, first \`cp -r <dir> <checkout>/entries/\`. Then, only with \`git -C <checkout>\`
@@ -102,6 +109,46 @@ and \`public-site\` are inspiration only and \`save_entry\` refuses \`tier: port
 - Never run git in the current project.`;
 }
 
+export function addBatchPrompt(ctx, a) {
+  const v = ctx.vocab.facets;
+  const given = Object.entries(a).filter(([, value]) => value).map(([key, value]) => `- ${key}: ${value}`).join('\n');
+  return `# Add a batch of design references to wp-design-library
+
+Arguments given:
+${given || '- (none)'}
+
+Use the hosted workflow end to end; do not edit the server filesystem.
+
+1. **Stage files.** If recordings are on this machine, run \`library upload\` once per file
+   with \`--server\`, \`--source\`, \`--license\`, and optional \`--url\`/\`--title\`.
+   Authentication comes from \`LIBRARY_TOKEN\`; never print it or put it in an argument.
+   Files already in the server inbox need no upload.
+2. **Draft.** Call \`add_batch\` once, passing the supplied source/licence as defaults for
+   files without sidecars. It resumes interrupted work, skips an existing slug,
+   and reports a refusal per bad file while continuing the rest. Report refusals, then keep
+   processing every drafted slug.
+3. **Inspect.** Call \`get_vocab\` once. For every drafted slug call \`get_draft\`; inspect
+   every returned strip image. Long recordings may need another capture before the motion
+   note can honestly cover every section.
+4. **Tag in chunks.** Build \`set_fields_batch.entries\` records and submit chunks of at
+   most 25 so results remain reviewable. Fill every blank. Roles must come from
+   ${list(v.role)}; feel from ${list(v.feel)}; motion devices from ${list(v.motion)}.
+   Each body has \`## What it does\`, \`## Section roster\`, and \`## Why it works\`.
+   Motion notes begin with the sampled-frame limitation and describe sections in order.
+   A refused item does not undo the others; fix it and resubmit only that slug.
+5. **Review.** Show a compact table containing slug, roles, feel, palette, motion devices,
+   and any refusal. Wait for the user's approval of the batch and apply requested changes.
+6. **Save once.** Call \`save_batch\` with all approved slugs. It validates each entry,
+   isolates failures, and rebuilds the index once. Fix and resubmit refused slugs without
+   repeating successful ones.
+7. **Ship.** Run \`library check --remote\`. For a hosted volume, use
+   \`library export --saved-only\` to bring entries into a checkout, then create one content
+   branch and PR for the batch.
+
+Never infer a visual field without inspecting its strip, never write provenance through
+\`set_fields_batch\`, and never drop a field merely to pass validation.`;
+}
+
 // brief-from-library turns a client brief into a reference set: one `recommend` call,
 // then `get_entry` on what survives, then a `## References` block the session fills in
 // with the slugs it actually used. The per-role `search` fan-out is kept as a fallback
@@ -157,7 +204,8 @@ export function registerPrompts(server, ctx) {
     {
       description: 'Add a design reference to the library: ingest a recording, tag it in this session per the rubric, approve the draft, save it, offer the PR.',
       argsSchema: {
-        path: z.string().describe('absolute path to an animated webp/gif or a video file'),
+        input: z.string().optional().describe('live page URL, inbox filename, or absolute local media path'),
+        path: z.string().optional().describe('legacy alias for an absolute local media path'),
         source: z.string().describe('own | open | paid | public-site'),
         slug: z.string().optional().describe('lowercase, digits and dashes'),
         title: z.string().optional(),
@@ -167,4 +215,17 @@ export function registerPrompts(server, ctx) {
     },
     async (a) => ({ messages: [{ role: 'user', content: { type: 'text', text: addEntryPrompt(ctx, a) } }] }),
   );
+
+  server.registerPrompt(
+    'add-batch',
+    {
+      description: 'Ingest, inspect, tag, review, and save every recording in the hosted inbox with batch tools and isolated failures.',
+      argsSchema: {
+        source: z.string().optional().describe('default own | open | paid | public-site when sidecars omit it'),
+        license: z.string().optional().describe('default licence text when sidecars omit it'),
+        server: z.string().optional().describe('hosted library origin used by library upload'),
+      },
+    },
+    async (a) => ({ messages: [{ role: 'user', content: { type: 'text', text: addBatchPrompt(ctx, a) } }] }),
+  );
 }

package/src/mcp/tools.mjs

@@ -43,7 +43,7 @@ function resolveFilters(vocab, filters = {}) {
 // (the operator running the CLI already has that file access), so it stays
 // unrestricted there. Shared by `add` (input) and `similar` (image).
 function confineToInbox(ctx, inputPath) {
-  if (ctx.transport !== 'http') return null;
+  if (ctx.transport !== 'http') return { path: inputPath, refused: null };
   // Realpath the inbox root itself (when it exists) so a symlinked <data>/inbox still
   // confines correctly: inputPath's own realpath resolves through that symlink too, and
   // comparing against the unresolved join would then never match.
@@ -53,9 +53,12 @@ function confineToInbox(ctx, inputPath) {
   // existsSync is false for a dangling symlink too, not just a missing path: refuse
   // both explicitly instead of falling through to path.resolve, which would let a
   // dangling symlink under inbox pass confinement on its unresolved path alone.
-  if (!fs.existsSync(inputPath)) return 'input does not exist';
-  const real = fs.realpathSync(inputPath);
-  return real.startsWith(inbox) ? null : 'over http, the path must be a file under <data>/inbox';
+  const candidate = path.isAbsolute(inputPath) ? inputPath : path.join(inboxRoot, inputPath);
+  if (!fs.existsSync(candidate)) return { path: candidate, refused: 'input does not exist' };
+  const real = fs.realpathSync(candidate);
+  return real.startsWith(inbox)
+    ? { path: real, refused: null }
+    : { path: real, refused: 'over http, the path must be a file under <data>/inbox' };
 }
 
 export function makeTools(ctx) {
@@ -129,6 +132,51 @@ export function makeTools(ctx) {
         return { ...out, body: first.trim(), detail: 'summary' };
       }),
     },
+    {
+      name: 'get_draft',
+      description: 'Return a saved or unsaved draft directly from the corpus volume, including blank judgement fields and every strip as paths, public URLs, and MCP image content. Use after add_batch because drafts are not searchable until saved.',
+      schema: z.object({ slug: z.string().regex(/^[a-z0-9-]+$/) }),
+      handler: async ({ slug }) => {
+        const dir = path.join(ctx.paths.entries, slug);
+        if (!fs.existsSync(path.join(dir, 'entry.md'))) return { refused: `no draft with slug ${slug}` };
+        const entry = parseEntry(dir);
+        const captures = entry.fm?.captured?.captures ?? [];
+        let config = null;
+        try { config = readConfig(); } catch { config = null; }
+        const strips = [];
+        const stripUrls = [];
+        for (const capture of captures) {
+          const artifact = (capture.artifacts ?? []).find((a) => a?.key?.endsWith('/strip.webp'));
+          if (!artifact) { strips.push(null); stripUrls.push(null); continue; }
+          let local = null;
+          try { local = await artifactFile(ctx.paths, artifact); } catch { local = null; }
+          strips.push(local);
+          stripUrls.push(config ? objectUrl(config, artifact.key) : null);
+        }
+        const { REQUIRED_BLANKS } = await import('../entry.mjs');
+        const view = { ...entry.fm, body: entry.body };
+        const valueAt = (dotted) => dotted.split('.').reduce((o, key) => (o == null ? undefined : o[key]), view);
+        const blanks = REQUIRED_BLANKS.filter((field) => {
+          const value = valueAt(field);
+          return value == null || value === '' || (Array.isArray(value) && value.length === 0);
+        });
+        return { ...entry, blanks, strip: strips[0] ?? null, strips, strip_url: stripUrls[0] ?? null, strip_urls: stripUrls };
+      },
+      content: (out) => {
+        if (out.refused) return [];
+        return (out.strips ?? []).flatMap((strip, index) => {
+          if (!strip) return [];
+          try {
+            return [
+              { type: 'text', text: `Capture ${index + 1} strip for ${out.fm.slug}` },
+              { type: 'image', mimeType: 'image/webp', data: fs.readFileSync(strip).toString('base64') },
+            ];
+          } catch {
+            return [{ type: 'text', text: `Capture ${index + 1} strip for ${out.fm.slug} became unavailable` }];
+          }
+        });
+      },
+    },
     {
       name: 'get_motion',
       description: 'Inspect one motion clip at original playback speed. Returns video URL when published, provenance, observed motion notes, and timestamped frames as native images by default. Use clip to select from available clips; timestamps are relative to the clip. A video URL alone does not provide video understanding.',
@@ -165,8 +213,9 @@ export function makeTools(ctx) {
       handler: withDb(async (db, a) => {
         if (!!a.slug === !!a.image) return { refused: 'similar needs exactly one of slug or image' };
         if (a.image) {
-          const refusal = confineToInbox(ctx, a.image);
-          if (refusal) return { refused: refusal };
+          const confined = confineToInbox(ctx, a.image);
+          if (confined.refused) return { refused: confined.refused };
+          a = { ...a, image: confined.path };
         }
         return similar(db, { ...a, embedder: ctx.embedder, embedderReason: ctx.embedderReason });
       }),
@@ -241,8 +290,9 @@ export function makeTools(ctx) {
           const refusal = await refuseUnsafeUrl(a.input, { transport: ctx.transport });
           if (refusal) return { refused: refusal };
         } else {
-          const refusal = confineToInbox(ctx, a.input);
-          if (refusal) return { refused: refusal };
+          const confined = confineToInbox(ctx, a.input);
+          if (confined.refused) return { refused: confined.refused };
+          a = { ...a, input: confined.path };
         }
         return (await import('../cli/add.mjs')).addEntry(a);
       },
@@ -282,6 +332,24 @@ export function makeTools(ctx) {
         return saveEntry({ dir: path.join(ctx.paths.entries, slug), vocab: ctx.vocab, indexPath: ctx.paths.index, entriesDir: ctx.paths.entries, models: ctx.paths.models, p: ctx.paths });
       },
     },
+    {
+      name: 'save_batch',
+      description: 'Validate and save many reviewed drafts, isolating invalid entries and rebuilding the index once for every valid slug. Returns one result per slug plus saved/refused counts.',
+      schema: z.object({
+        slugs: z.array(z.string().regex(/^[a-z0-9-]+$/)).min(1).max(2000),
+      }),
+      handler: async ({ slugs }) => {
+        const { saveEntries } = await import('../ingest/save.mjs');
+        return saveEntries({
+          dirs: slugs.map((slug) => path.join(ctx.paths.entries, slug)),
+          vocab: ctx.vocab,
+          indexPath: ctx.paths.index,
+          entriesDir: ctx.paths.entries,
+          models: ctx.paths.models,
+          p: ctx.paths,
+        });
+      },
+    },
     {
       name: 'set_fields',
       description: "Fill a draft's judgement fields: roles, feel, motion.devices, motion.notes, palette, type, body, tier, ported_from — never provenance. Vocabulary terms are resolved through aliases and an unknown one is refused by name with nothing written, so a refusal never leaves a half-filled draft. Returns the fields still blank. This is the step between add and save_entry, and it is the only one that does not need a filesystem.",
@@ -294,6 +362,34 @@ export function makeTools(ctx) {
         return setFields({ dir: path.join(ctx.paths.entries, slug), fields, vocab: ctx.vocab });
       },
     },
+    {
+      name: 'set_fields_batch',
+      description: 'Fill judgement fields for many drafts in one call. Each entry is isolated: an unknown term, provenance field, or missing slug refuses only that item and never partially writes it. Use chunks small enough to inspect, then save_batch after review.',
+      schema: z.object({
+        entries: z.array(z.object({
+          slug: z.string().regex(/^[a-z0-9-]+$/),
+          fields: z.record(z.any()),
+        })).min(1).max(200),
+      }),
+      handler: async ({ entries }) => {
+        const { setFields } = await import('../ingest/fields.mjs');
+        const seen = new Set();
+        const results = entries.map(({ slug, fields }) => {
+          if (seen.has(slug)) return { ok: false, slug, written: [], refused: ['duplicate slug in batch'] };
+          seen.add(slug);
+          try {
+            return setFields({ dir: path.join(ctx.paths.entries, slug), fields, vocab: ctx.vocab });
+          } catch (err) {
+            return { ok: false, slug, written: [], refused: [err.message] };
+          }
+        });
+        return {
+          results,
+          updated: results.filter((r) => r.ok).length,
+          refused: results.filter((r) => !r.ok).length,
+        };
+      },
+    },
   ];
 }