scanruler-mcp 0.4.0 → 0.4.5

package/src/relay.js

@@ -24,6 +24,9 @@ export class PeerLink extends Asker {
     this.token = token
     this.version = version
     this.log = log
+    /** The holding copy's version, as its welcome said; null from a copy
+     *  before 0.4.1, whose welcome to another copy carried none. */
+    this.holderVersion = null
   }
 
   /** Connect to the copy on the port. Resolves `{ ok: true }` once it took
@@ -40,6 +43,7 @@ export class PeerLink extends Asker {
           if (message.welcome) {
             accepted = true
             this.socket = ws
+            this.holderVersion = typeof message.welcome.version === 'string' ? message.welcome.version : null
             this.#setPage(message.welcome.page ?? null)
             resolve({ ok: true })
           } else resolve({ refused: String(message.refused ?? 'It said no.') })
@@ -141,6 +145,12 @@ export class SharedLink extends EventEmitter {
     return this.current?.page ?? null
   }
 
+  /** While relaying: the version of the copy holding the port, null when
+   *  it is from before 0.4.1 and did not say. Undefined otherwise. */
+  get holderVersion() {
+    return this.role === 'relay' ? (this.peer?.holderVersion ?? null) : undefined
+  }
+
   run(name, input, binaryKey, onProgress, job, deferred = false) {
     const link = this.current
     if (!link) return Promise.reject({ code: 'unavailable', message: 'No ScanRuler page is connected.' })

package/src/tools.js

@@ -20,31 +20,38 @@ export function bytesProperty(command) {
   return Object.keys(props).find((key) => props[key]?.type === 'string' && props[key]?.format === 'binary') ?? null
 }
 
-const inPath = {
+/** Where a relative path is taken from, as every path field says it: the
+ *  folder a scan or a project was last opened from or saved into — as
+ *  scanruler_write and scanruler_files take it — else the folder the
+ *  server started in (mcp.js, pathBase). */
+export const relativeFrom = (cwd) =>
+  `A relative path is taken from the folder of the scan or project last opened or saved (scanruler_status: server.relativeTo) — before any, from ${cwd ?? 'the folder this server started in'}.`
+
+const inPath = (cwd) => ({
   type: 'string',
   minLength: 1,
-  description: 'The file to read, on this computer: an absolute path, or one relative to the folder the agent works in.',
-}
+  description: `The file to read, on this computer: an absolute path, or a relative one. ${relativeFrom(cwd)}`,
+})
 
-const outPath = (outDir) => ({
+const outPath = (outDir, cwd) => ({
   type: 'string',
   minLength: 1,
-  description: `Where to write the file: a file path, or a folder to write it into under the name ScanRuler gives it. Without it, it goes into ${outDir}.`,
+  description: `Where to write the file: a file path — one there already is replaced — or a folder (one there, or a path ending in /) to write it into under the name ScanRuler gives it, numbered past a file of that name there (-2, -3 …). Without it, it goes into ${outDir} the same way. ${relativeFrom(cwd)}`,
 })
 
-const imagePath = (outDir) => ({
+const imagePath = (outDir, cwd) => ({
   type: 'string',
   minLength: 1,
-  description: `Also write the picture to a file: a file path, or a folder to write it into under the name ScanRuler gives it. Without it, it is only shown — but in scanruler_batch, which shows no picture, it is written into ${outDir} under a new name.`,
+  description: `Also write the picture to a file: a file path — one there already is replaced — or a folder (one there, or a path ending in /) to write it into under the name ScanRuler gives it, numbered past a picture of that name there (-2, -3 …). Without it, it is only shown — but in scanruler_batch, which shows no picture, it is written under a new name into the folder of the scan or project last opened or saved (the latest of scanruler_status folders), before any into ${outDir}. ${relativeFrom(cwd)}`,
 })
 
 /** The `saveTo` a command that replaces the session takes — one with
  *  `discard`: the session saved as a project file first (mcp.js). */
-const saveToIn = {
+const saveToIn = (cwd) => ({
   type: 'string',
   minLength: 1,
-  description: 'Save the session as a .scanruler project file here first — a file path, or a folder to save it into under its own name — then go on as with discard: true. If the save fails nothing is replaced. The answer says where it went (savedTo).',
-}
+  description: `Save the session as a .scanruler project file here first — a file path, or a folder to save it into under its own name — then go on as with discard: true. If the save fails nothing is replaced. The answer says where it went (savedTo). ${relativeFrom(cwd)}`,
+})
 
 /** Whether a command replaces the session, refusing to over work unless
  *  told `discard` — what `saveTo` is offered on. */
@@ -93,7 +100,7 @@ export const timingsIn = {
   description: 'true: the answer adds ms (the call, start to answer) and, where the change built, steps.played — each step the build played with its ms (steps.restored counts those taken up from a kept state, not played).',
 }
 
-export function toolFor(command, { outDir }) {
+export function toolFor(command, { outDir, cwd }) {
   const input = structuredClone(command.input ?? { type: 'object' })
   input.properties = { ...(input.properties ?? {}) }
   let required = [...(input.required ?? [])]
@@ -102,7 +109,8 @@ export function toolFor(command, { outDir }) {
   if (bytesKey) {
     delete input.properties[bytesKey]
     const pick = FOLDER_PICKS[command.name]
-    input.properties.path = pick ? { ...inPath, description: `${inPath.description} A folder opens the one ${pick.what} file in it (${pick.kinds.join(', ')}); with more than one, the answer lists them.` } : inPath
+    const read = inPath(cwd)
+    input.properties.path = pick ? { ...read, description: `${read.description} A folder opens the one ${pick.what} file in it (${pick.kinds.join(', ')}); with more than one, the answer lists them.` } : read
     required = required.filter((key) => key !== bytesKey && key !== 'name')
     if (!required.includes('path')) required.unshift('path')
     if (input.properties.name) {
@@ -111,15 +119,15 @@ export function toolFor(command, { outDir }) {
     description += ' The file is read from `path` on this computer and streamed to the page.'
   }
   if (command.returnsImage) {
-    input.properties.path = imagePath(outDir)
+    input.properties.path = imagePath(outDir, cwd)
     input.properties.inline = inlineIn
     description += ' The picture comes back as an image; with `path` it is written to a file too, and with `inline: false` only there.'
   } else if (command.returnsFile) {
-    input.properties.path = outPath(outDir)
+    input.properties.path = outPath(outDir, cwd)
     description += ' The file is written to `path`; the result says where and how large it is, not its bytes.'
   }
   if (replacesSession(command)) {
-    input.properties.saveTo = saveToIn
+    input.properties.saveTo = saveToIn(cwd)
     description += ' With `saveTo`, the session is saved as a project file there first (as project_save does), then replaced as with discard: true — one call to keep what a page holds and start anew.'
   }
   if (!command.readOnly) {
@@ -259,7 +267,8 @@ export async function inputFor(command, args, { cwd }) {
 /** Arguments with every `{ "$file": path }` in them — an object of that one
  *  key, at any depth — replaced by the JSON the file holds: a long list of
  *  stations a script wrote need not pass through the conversation. A
- *  relative path is taken from `cwd`. What a file holds is not looked
+ *  relative path is taken from `cwd` — the folder the server takes
+ *  relative paths from (mcp.js, pathBase). What a file holds is not looked
  *  into again. */
 export async function withFiles(value, cwd) {
   if (Array.isArray(value)) return Promise.all(value.map((v) => withFiles(v, cwd)))
@@ -308,32 +317,63 @@ export async function imageContent(result, args, { cwd, outDir }) {
   ]
 }
 
-/** A picture a batched call handed back, which a batch cannot show:
- *  written where the call asked, or into `outDir` under the name ScanRuler
- *  gave it — numbered past one already there, so a batch of renders, or a
- *  render from an earlier batch, is not written over. The result says
- *  where, in place of the bytes. A result with no picture in it is as
- *  saveFileResult leaves it. */
-export async function batchedPicture(result, args, { cwd, outDir }) {
-  const file = result?.file
-  if (args?.path || !file || !(file.bytes instanceof Uint8Array)) return saveFileResult(result, args, { cwd, outDir })
-  const name = String(file.name ?? 'picture.png')
+/** How many numbered names writeNew tries before it gives up. */
+const NUMBERED_MOST = 10_000
+
+/** `data` written to a new file in `folder` under `name` — or, a file of
+ *  that name being there, as `stem-2.ext`, `stem-3.ext` …: each is made
+ *  with `wx`, which refuses one that is there, so two written at once —
+ *  pictures rendered side by side, answers spilled together — never take
+ *  the same name, and nothing earlier is written over. Returns its path. */
+export async function writeNew(folder, name, data) {
+  await mkdir(folder, { recursive: true })
   const dot = name.lastIndexOf('.')
   const [stem, ext] = dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, '']
-  let target = join(outDir, name)
-  for (let n = 2; await stat(target).catch(() => null); n++) target = join(outDir, `${stem}-${n}${ext}`)
-  return saveFileResult(result, { path: target }, { cwd, outDir })
+  for (let n = 1; n <= NUMBERED_MOST; n++) {
+    const target = join(folder, n === 1 ? name : `${stem}-${n}${ext}`)
+    try {
+      await writeFile(target, data, { flag: 'wx' })
+      return target
+    } catch (e) {
+      if (e?.code !== 'EEXIST') throw e
+    }
+  }
+  throw { code: 'failed', message: `${folder} already holds ${NUMBERED_MOST} files named like ${name}: give a path to write it to.` }
+}
+
+/** A picture a batched call handed back, which a batch cannot show:
+ *  written where the call asked, or into `folder` — the latest a scan or
+ *  a project came from, which a sandboxed agent can open — else, or when
+ *  that folder takes no file, into `outDir`; as saveFileResult writes any
+ *  file, numbered past one already there, so a batch of renders, or a
+ *  render from an earlier batch, is not written over. The result says
+ *  where, in place of the bytes. */
+export async function batchedPicture(result, args, { cwd, outDir, folder }) {
+  if (args?.path || !folder) return saveFileResult(result, args, { cwd, outDir })
+  try {
+    return await saveFileResult(result, args, { cwd, outDir: folder })
+  } catch {
+    return saveFileResult(result, args, { cwd, outDir })
+  }
 }
 
 /** Write a returned file where the call asked, or into `outDir`; the result
- *  then says where, in place of the bytes. */
+ *  then says where, in place of the bytes. A file path given is written,
+ *  over one there; a folder — one there, or a path ending in a separator —
+ *  or `outDir` takes the name ScanRuler gave the file, numbered past one
+ *  already there (writeNew). */
 export async function saveFileResult(result, args, { cwd, outDir }) {
   const file = result?.file
   if (!file || !(file.bytes instanceof Uint8Array)) return result
-  let target = args?.path ? absolute(String(args.path), cwd) : join(outDir, file.name)
-  const existing = await stat(target).catch(() => null)
-  if (existing?.isDirectory()) target = join(target, file.name)
-  await mkdir(dirname(target), { recursive: true })
-  await writeFile(target, file.bytes)
+  const name = basename(String(file.name ?? 'file'))
+  const given = args?.path ? absolute(String(args.path), cwd) : null
+  const folder = given === null ? outDir : /[\\/]$/.test(String(args.path)) || (await stat(given).catch(() => null))?.isDirectory() ? given : null
+  let target
+  if (folder !== null) target = await writeNew(folder, name, file.bytes)
+  else {
+    target = given
+    await mkdir(dirname(target), { recursive: true })
+    await writeFile(target, file.bytes)
+  }
   return { ...result, file: { name: file.name, mimeType: file.mimeType, size: file.bytes.byteLength, path: target } }
 }