severally-mcp 2.4.0 → 2.5.0

package/src/expose-paths.mjs

@@ -22,7 +22,58 @@ import { spawnSync } from 'node:child_process';
 import { POLICY, isProtectedPath } from './policy.mjs';
 import { redact } from './redact.mjs';
 
+/** @typedef {{ files: number, bytes: number }} ExposeTotals */
+
+/**
+ * A path left out of the copy, with why: 'ignored', 'symlink', 'protected',
+ * 'submodule', 'gone', 'masked' or 'replaced'. `exposed_as` names it where a
+ * follow-up carries over an earlier round's entry.
+ * @typedef {{ source: string, reason: string, exposed_as?: string | undefined }} SkippedPath
+ */
+
+/**
+ * One exposed entry as the walk and the copy report it. `kind` is 'file',
+ * 'directory', 'diff' or 'change_files'.
+ * @typedef {object} ExposeEntry
+ * @property {number} index
+ * @property {string} source
+ * @property {string} kind
+ * @property {string} exposedAs
+ * @property {number} files
+ * @property {number} bytes
+ * @property {string[]} paths
+ * @property {string | null} [sha256]
+ * @property {string | undefined} [base]
+ * @property {string[]} [changes]
+ * @property {boolean} [changed] a follow-up's copy of a parent path: whether its bytes changed since
+ * @property {boolean} [inherited] a follow-up copied it again from the parent round
+ */
+
+/**
+ * What an expose_paths request comes to: the entries, their totals, and what was left out.
+ * @typedef {{ entries: ExposeEntry[], totals: ExposeTotals, skipped: SkippedPath[] }} ExposeManifest
+ */
+
+/** A path as the lead names it, or as an earlier round numbered it. @typedef {string | { source: string, index: number }} ExposePathSpec */
+
+/**
+ * An entry of an earlier round's brief record (briefRecord's `expose_paths.entries`).
+ * @typedef {object} ExposedEntryRecord
+ * @property {number} index
+ * @property {string} source
+ * @property {string | undefined} [exposed_as]
+ * @property {string | undefined} [kind]
+ * @property {string | undefined} [base]
+ * @property {string[] | undefined} [changes]
+ */
+
+/** @typedef {{ path: string, status: string }} RepoChange */
+
 export class ExposeError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} code
+   */
   constructor(message, code) {
     super(message);
     this.name = 'ExposeError';
@@ -30,7 +81,13 @@ export class ExposeError extends Error {
   }
 }
 
-/** A size a reader can judge at a glance; the brief is read, not parsed. */
+/** @param {unknown} err */
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+
+/**
+ * A size a reader can judge at a glance; the brief is read, not parsed.
+ * @param {number} bytes
+ */
 export function humanSize(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   const kb = bytes / 1024;
@@ -42,6 +99,7 @@ export function humanSize(bytes) {
 // Getting it wrong is survivable in one direction only -- a binary treated as
 // text would be corrupted by redact()'s utf8 round-trip, so the test errs
 // toward calling things binary.
+/** @param {Uint8Array} buf */
 function isBinary(buf) {
   const len = Math.min(buf.length, 8_000);
   for (let i = 0; i < len; i++) if (buf[i] === 0) return true;
@@ -50,10 +108,15 @@ function isBinary(buf) {
 
 // Before a file is read: the caps are a few megabytes, and a 1 GB file must
 // be refused by its size, not after it has been read into memory and written.
+/**
+ * @param {ExposeTotals} totals
+ * @param {number} size
+ */
 function ensureRoom(totals, size) {
   checkBudget({ files: totals.files + 1, bytes: totals.bytes + size });
 }
 
+/** @param {ExposeTotals} totals */
 function checkBudget(totals) {
   if (totals.files > POLICY.input.exposeFilesMax) {
     throw new ExposeError(
@@ -74,12 +137,13 @@ function checkBudget(totals) {
 // A path the lead named, as opposed to one found while walking: it is refused
 // rather than skipped, because a lead who typed a symlink meant something by
 // it and should hear which entry could not be used.
+/** @param {string} source */
 function statEntry(source) {
   let stat;
   try {
     stat = fs.lstatSync(source);
   } catch (err) {
-    throw new ExposeError(`expose_paths entry "${source}" cannot be read: ${err.message}`, 'not_found');
+    throw new ExposeError(`expose_paths entry "${source}" cannot be read: ${messageOf(err)}`, 'not_found');
   }
   if (stat.isSymbolicLink()) {
     throw new ExposeError(`expose_paths entry "${source}" is a symlink; name the path it points at instead`, 'invalid_type');
@@ -94,6 +158,13 @@ function statEntry(source) {
 // accounts for the file (it owns the totals), and the budget is checked after
 // every single one, so an oversized tree stops at the file that crossed the
 // line rather than after the whole thing has been walked or copied.
+/**
+ * @param {string} root
+ * @param {string} dir
+ * @param {(abs: string, rel: string) => void} onFile
+ * @param {ExposeTotals} totals
+ * @param {SkippedPath[]} skipped
+ */
 function walkDir(root, dir, onFile, totals, skipped) {
   let items;
   try {
@@ -101,7 +172,7 @@ function walkDir(root, dir, onFile, totals, skipped) {
     // entries were created.
     items = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   } catch (err) {
-    throw new ExposeError(`expose_paths entry "${dir}" cannot be read: ${err.message}`, 'not_found');
+    throw new ExposeError(`expose_paths entry "${dir}" cannot be read: ${messageOf(err)}`, 'not_found');
   }
   for (const item of items) {
     const child = path.join(dir, item.name);
@@ -138,10 +209,18 @@ function walkDir(root, dir, onFile, totals, skipped) {
 
 // walkDir's order: name by name at every level, not the whole path as one
 // string ("a/x" comes before "a-b" there, after it as a string).
+/**
+ * @param {string} a
+ * @param {string} b
+ */
 function byPathParts(a, b) {
   const x = a.split('/');
   const y = b.split('/');
-  for (let i = 0; i < Math.min(x.length, y.length); i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  for (const [i, part] of x.entries()) {
+    const other = y[i];
+    if (other === undefined) break;
+    if (part !== other) return part < other ? -1 : 1;
+  }
   return x.length - y.length;
 }
 
@@ -152,6 +231,14 @@ function byPathParts(a, b) {
 // submodule, or reach outside the directory. False when this is not a work
 // tree, git is missing or lists nothing (an ignored directory the lead named
 // on purpose): the caller walks it instead.
+/**
+ * @param {string} dir
+ * @param {string} exposedAs
+ * @param {(abs: string, rel: string) => void} onFile
+ * @param {ExposeTotals} totals
+ * @param {SkippedPath[]} skipped
+ * @returns {boolean}
+ */
 function walkGit(dir, exposedAs, onFile, totals, skipped) {
   let listed;
   let ignored;
@@ -217,8 +304,14 @@ function walkGit(dir, exposedAs, onFile, totals, skipped) {
 
 // Each path is a string, or { source, index } to keep the name an earlier
 // round gave it.
+/**
+ * @param {ExposePathSpec[]} exposePaths
+ * @param {(abs: string, rel: string, index: number, source: string, totals: ExposeTotals) => void} onFile
+ * @returns {ExposeManifest}
+ */
 function walkEntries(exposePaths, onFile) {
   const totals = { files: 0, bytes: 0 };
+  /** @type {SkippedPath[]} */
   const skipped = [];
   const entries = exposePaths.map((p, i) => {
     const { source, index } = typeof p === 'string' ? { source: p, index: i } : p;
@@ -229,6 +322,7 @@ function walkEntries(exposePaths, onFile) {
     const before = { files: totals.files, bytes: totals.bytes };
     // What a directory holds, for the brief: not every consultant has a tool
     // that lists a directory, and a name it cannot see is a file it never reads.
+    /** @type {string[]} */
     const paths = [];
     if (isProtectedPath(source)) {
       skipped.push({ source, reason: 'protected' });
@@ -236,6 +330,7 @@ function walkEntries(exposePaths, onFile) {
       onFile(source, '', index, source, totals);
       checkBudget(totals);
     } else {
+      /** @type {(abs: string, rel: string) => void} */
       const add = (abs, rel) => {
         paths.push(rel.split(path.sep).join('/'));
         onFile(abs, rel, index, source, totals);
@@ -261,6 +356,8 @@ function walkEntries(exposePaths, onFile) {
  * real copy may write slightly fewer bytes once a text file's
  * credential-shaped strings are masked, which only ever shrinks what was
  * already reported.
+ * @param {ExposePathSpec[] | null | undefined} exposePaths
+ * @returns {ExposeManifest | null}
  */
 export function previewExposePaths(exposePaths) {
   if (!exposePaths || exposePaths.length === 0) return null;
@@ -277,11 +374,15 @@ export function previewExposePaths(exposePaths) {
  * are copied unchanged, since a utf8 round-trip would corrupt them. Walks
  * from scratch and re-checks the caps, so a tree that grew or vanished since
  * the preview fails here instead of being copied in part.
+ * @param {string} workdir
+ * @param {ExposePathSpec[] | null | undefined} exposePaths
+ * @returns {ExposeManifest | null}
  */
 export function materializeExposedPaths(workdir, exposePaths) {
   if (!exposePaths || exposePaths.length === 0) return null;
   const root = path.join(workdir, 'workspace');
   fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  /** @type {import('node:crypto').Hash[]} */
   const hashes = [];
   const manifest = walkEntries(exposePaths, (abs, rel, index, source, totals) => {
     ensureRoom(totals, fs.statSync(abs).size);
@@ -297,6 +398,10 @@ export function materializeExposedPaths(workdir, exposePaths) {
 
 // The bytes a consultant gets for one file, written to dest: valid-utf8 text
 // through redact(), anything else unchanged.
+/**
+ * @param {string} abs
+ * @param {string} dest
+ */
 function copyMasked(abs, dest) {
   const buf = fs.readFileSync(abs);
   let out = buf;
@@ -319,12 +424,21 @@ function copyMasked(abs, dest) {
 // sha256 covers the copies in path order, so the same files give the same
 // hash however they were found. `gone` is where a path that no longer exists
 // goes; by default it is dropped, as a change listing a vanished path is.
+/**
+ * @param {string} workdir
+ * @param {string} top
+ * @param {RepoChange[]} changes
+ * @param {ExposeManifest} manifest
+ * @param {(c: RepoChange) => void} shown
+ * @param {((c: RepoChange) => void) | null} [gone]
+ */
 function copyRepoFiles(workdir, top, changes, manifest, shown, gone = null) {
   const root = path.join(workdir, 'workspace', 'repo');
   // Made even when nothing is copied (a change that only deletes): each
   // member's workspace is copied from here.
   fs.mkdirSync(root, { recursive: true, mode: 0o700 });
   const realTop = fs.realpathSync(top);
+  /** @type {{ path: string, size: number }[]} */
   const copied = [];
   for (const c of changes) {
     const abs = path.join(top, c.path);
@@ -388,11 +502,17 @@ function copyRepoFiles(workdir, top, changes, manifest, shown, gone = null) {
  * ('masked'). The parent's diff is not taken again: the files it touched are
  * re-copied as they are now (`diffs`, for reexposeChange), because a diff
  * against a base that has since moved would be a different change.
+ * @param {ExposedEntryRecord[]} parentEntries
+ * @param {string[]} exposePaths
  */
 export function planInheritance(parentEntries, exposePaths) {
+  /** @type {{ source: string, index: number }[]} */
   const paths = [];
+  /** @type {SkippedPath[]} */
   const skipped = [];
+  /** @type {ExposedEntryRecord[]} */
   const diffs = [];
+  /** @param {string} p */
   const exists = (p) => {
     try {
       fs.lstatSync(p);
@@ -433,12 +553,17 @@ export function planInheritance(parentEntries, exposePaths) {
  * The files an earlier round's change touched, copied again under
  * workspace/repo/ as they are now, added to `manifest` as a 'change_files'
  * entry. Read from that round's record of the change, not from git.
+ * @param {string} workdir
+ * @param {ExposedEntryRecord} entry
+ * @param {ExposeManifest} manifest
+ * @returns {boolean}
  */
 export function reexposeChange(workdir, entry, manifest) {
+  /** @type {RepoChange[]} */
   const changes = [];
   for (const c of entry.changes ?? []) {
     const m = /^(.*) \(([^()]+)\)$/.exec(c);
-    const p = m ? m[1] : c;
+    const p = m?.[1] ?? c;
     if (p.includes('[REDACTED')) {
       manifest.skipped.push({ source: path.join(entry.source, p), reason: 'masked', exposed_as: `workspace/repo/${p}` });
       continue;
@@ -456,6 +581,7 @@ export function reexposeChange(workdir, entry, manifest) {
     changes.push({ path: p, status: deleted ? (back ? 'restored' : 'D') : (m?.[2] ?? 'M') });
   }
   const before = { ...manifest.totals };
+  /** @type {RepoChange[]} */
   const shown = [];
   const { copied, sha256 } = copyRepoFiles(
     workdir,
@@ -496,6 +622,10 @@ export function reexposeChange(workdir, entry, manifest) {
 // switched off, pathspecs are literal, and no shell is involved.
 // ponytail: a clean filter (filter.<driver>.clean in .git/config) still runs
 // on `git diff` of the working tree; .git/config is local, not cloned.
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ */
 function git(cwd, args) {
   // Without the server's own GIT_* (GIT_DIR, GIT_INDEX_FILE ... would point
   // at another repository), and without taking the lead's index lock.
@@ -508,7 +638,7 @@ function git(cwd, args) {
   });
   if (r.error || r.status !== 0) {
     const why =
-      /** @type {NodeJS.ErrnoException} */ (r.error)?.code === 'ENOENT'
+      r.error && 'code' in r.error && r.error.code === 'ENOENT'
         ? 'git is not on PATH'
         : String(r.stderr ?? r.error?.message ?? '').trim();
     throw new ExposeError(`context.expose_diff: git ${args[0]} failed in "${cwd}": ${why}`, 'not_found');
@@ -516,6 +646,7 @@ function git(cwd, args) {
   return r.stdout;
 }
 
+/** @param {Buffer} buf */
 const nulSplit = (buf) => buf.toString('utf8').split('\0').filter(Boolean);
 
 /**
@@ -525,6 +656,11 @@ const nulSplit = (buf) => buf.toString('utf8').split('\0').filter(Boolean);
  * name the copies; deleted files are listed, not copied. Protected paths are
  * left out of the copy and of the diff. Returns the diff text, masked and cut
  * to maxChars, for the brief.
+ * @param {string} workdir
+ * @param {{ repo: string, base?: string | undefined }} source
+ * @param {ExposeManifest} manifest
+ * @param {number} maxChars
+ * @returns {string}
  */
 export function exposeDiff(workdir, { repo, base = 'HEAD' }, manifest, maxChars) {
   const top = git(repo, ['rev-parse', '--show-toplevel']).toString('utf8').trim();
@@ -532,12 +668,18 @@ export function exposeDiff(workdir, { repo, base = 'HEAD' }, manifest, maxChars)
   const tokens = nulSplit(
     git(top, ['diff', '--name-status', '-z', '--no-renames', '--no-relative', '--no-ext-diff', '--no-textconv', base, '--']),
   );
+  /** @type {RepoChange[]} */
   const changes = [];
-  for (let i = 0; i + 1 < tokens.length; i += 2) changes.push({ status: tokens[i], path: tokens[i + 1] });
+  for (let i = 0; i + 1 < tokens.length; i += 2) {
+    const status = tokens[i];
+    const file = tokens[i + 1];
+    if (status !== undefined && file !== undefined) changes.push({ status, path: file });
+  }
   for (const p of nulSplit(git(top, ['ls-files', '--others', '--exclude-standard', '-z'])))
     changes.push({ status: 'untracked', path: p });
 
   const before = { ...manifest.totals };
+  /** @type {RepoChange[]} */
   const shown = [];
   const { copied, sha256 } = copyRepoFiles(workdir, top, changes, manifest, (c) => shown.push(c));
   if (shown.length === 0) {

package/src/failures.mjs

@@ -36,13 +36,20 @@ const RULES = [
   ],
 ];
 
+/**
+ * @param {string | null | undefined} text
+ * @param {string} [fallback]
+ */
 export function classifyMessage(text, fallback = 'cli_error') {
   if (!text) return fallback;
   for (const [re, kind] of RULES) if (re.test(text)) return kind;
   return fallback;
 }
 
-/** Whether the lead may reasonably try again (with a longer budget, or later). */
+/**
+ * Whether the lead may reasonably try again (with a longer budget, or later).
+ * @param {string} kind
+ */
 export function isRetriable(kind) {
   return kind === 'timeout' || kind === 'cli_error' || kind === 'rate_limited' || kind === 'interrupted';
 }