@oddessentials/agent-guild 0.33.1 → 0.34.0

package/src/manager/environment-pins.mjs

@@ -0,0 +1,289 @@
+// Project pin files only. A pin is what a file asks for, never proof that a
+// runtime is installed or which binary a shell would execute.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const PIN_LIMIT = 64 * 1024;
+export const PIN_TEXT_MAX = 128;
+
+export const PIN_NAMES = [
+  '.nvmrc', '.node-version', '.python-version', 'package.json', 'pyproject.toml',
+  'rust-toolchain.toml', 'rust-toolchain', 'go.mod', 'global.json', '.tool-versions',
+];
+
+const TOOL_VERSIONS = {
+  node: ['tool-versions-node', 'Node.js'],
+  nodejs: ['tool-versions-node', 'Node.js'],
+  python: ['tool-versions-python', 'Python'],
+  go: ['tool-versions-go', 'Go'],
+  golang: ['tool-versions-go', 'Go'],
+  rust: ['tool-versions-rust', 'Rust'],
+  dotnet: ['tool-versions-dotnet', '.NET SDK'],
+  'dotnet-sdk': ['tool-versions-dotnet', '.NET SDK'],
+};
+
+function pin(id, label, source, status, version = null, detail = null) {
+  return { id, label, source, version, status, detail };
+}
+
+function configured(id, label, source, version) {
+  const text = typeof version === 'string' ? version.trim() : '';
+  if (!text) return pin(id, label, source, 'invalid', null, 'The pin is empty.');
+  if (text.length > PIN_TEXT_MAX) return pin(id, label, source, 'invalid', null, 'The pin is longer than 128 characters.');
+  return pin(id, label, source, 'configured', text);
+}
+
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+function versionLine(text) {
+  for (const raw of stripBom(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    return line;
+  }
+  return null;
+}
+
+function textPin(id, label, source, text) {
+  const line = versionLine(text);
+  if (line === null) return [pin(id, label, source, 'invalid', null, 'The pin file has no version.')];
+  return [configured(id, label, source, line)];
+}
+
+function packagePins(text) {
+  let data;
+  try { data = JSON.parse(stripBom(text)); } catch {
+    return [pin('package-json', 'package.json', 'package.json', 'invalid', null, 'package.json could not be read as JSON.')];
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return [pin('package-json', 'package.json', 'package.json', 'invalid', null, 'package.json could not be read as JSON.')];
+  }
+  const pins = [];
+  if (data.engines !== undefined) {
+    if (!data.engines || typeof data.engines !== 'object' || Array.isArray(data.engines)) {
+      pins.push(pin('engines', 'package.json', 'package.json', 'invalid', null, 'engines is not an object.'));
+    } else {
+      for (const [key, id, label] of [['node', 'engines-node', 'Node.js'], ['npm', 'engines-npm', 'npm']]) {
+        if (data.engines[key] === undefined) continue;
+        if (typeof data.engines[key] !== 'string') pins.push(pin(id, label, 'package.json', 'invalid', null, `engines.${key} is not a string.`));
+        else pins.push(configured(id, label, 'package.json', data.engines[key]));
+      }
+    }
+  }
+  if (data.packageManager !== undefined) {
+    if (typeof data.packageManager !== 'string') pins.push(pin('package-manager', 'packageManager', 'package.json', 'invalid', null, 'packageManager is not a string.'));
+    else {
+      const name = data.packageManager.split('@')[0].trim();
+      pins.push(configured('package-manager', name || 'packageManager', 'package.json', data.packageManager));
+    }
+  }
+  return pins;
+}
+
+function pythonRequires(text) {
+  const lines = stripBom(text).split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
+  const keys = lines.filter((line) => /^requires-python\s*=/.test(line));
+  if (!keys.length) return [];
+  if (keys.length !== 1) return [pin('requires-python', 'Python', 'pyproject.toml', 'invalid', null, 'requires-python is not a single-line string.')];
+  const match = /^requires-python\s*=\s*(["'])([^"']+)\1\s*(?:#.*)?$/.exec(keys[0]);
+  if (!match) return [pin('requires-python', 'Python', 'pyproject.toml', 'invalid', null, 'requires-python is not a single-line string.')];
+  return [configured('requires-python', 'Python', 'pyproject.toml', match[2])];
+}
+
+function rustToml(text) {
+  let section = '';
+  let channel = null;
+  let saw = false;
+  let bad = false;
+  for (const raw of stripBom(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const heading = /^\[([^\]]+)\]$/.exec(line);
+    if (heading) {
+      section = heading[1].trim();
+      if (section === 'toolchain') saw = true;
+      continue;
+    }
+    if (section !== 'toolchain' || !/^channel\s*=/.test(line)) continue;
+    const match = /^channel\s*=\s*(["'])([^"']+)\1\s*(?:#.*)?$/.exec(line);
+    if (!match || channel !== null) bad = true;
+    else channel = match[2];
+  }
+  if (bad || (saw && channel === null)) return [pin('rust-toolchain', 'Rust', 'rust-toolchain.toml', 'invalid', null, 'rust-toolchain channel is not a single-line string.')];
+  return channel === null ? [] : [configured('rust-toolchain', 'Rust', 'rust-toolchain.toml', channel)];
+}
+
+function rustFile(text) {
+  const line = versionLine(text);
+  if (line === null) return [pin('rust-toolchain-file', 'Rust', 'rust-toolchain', 'invalid', null, 'The pin file has no version.')];
+  if (line.startsWith('[')) return [pin('rust-toolchain-file', 'Rust', 'rust-toolchain', 'invalid', null, 'rust-toolchain is not a single version line.')];
+  return [configured('rust-toolchain-file', 'Rust', 'rust-toolchain', line)];
+}
+
+function goMod(text) {
+  let language = null;
+  let toolchain = null;
+  let bad = false;
+  for (const raw of stripBom(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('//')) continue;
+    if (/^go\s/.test(line)) {
+      const match = /^go\s+(\S+)$/.exec(line);
+      if (!match || language !== null) bad = true;
+      else language = match[1];
+    } else if (/^toolchain\s/.test(line)) {
+      const match = /^toolchain\s+(\S+)$/.exec(line);
+      if (!match || toolchain !== null) bad = true;
+      else toolchain = match[1];
+    }
+  }
+  if (bad) return [pin('go-mod', 'Go', 'go.mod', 'invalid', null, 'go.mod has a version line that could not be read.')];
+  const pins = [];
+  if (language) pins.push(configured('go-language', 'Go language', 'go.mod', language));
+  if (toolchain) pins.push(configured('go-toolchain', 'Go toolchain', 'go.mod', toolchain));
+  return pins;
+}
+
+function globalJson(text) {
+  let data;
+  try { data = JSON.parse(stripBom(text)); } catch {
+    return [pin('global-json', '.NET SDK', 'global.json', 'invalid', null, 'global.json could not be read as JSON.')];
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data) || data.sdk === undefined) return [];
+  if (!data.sdk || typeof data.sdk !== 'object' || Array.isArray(data.sdk) || typeof data.sdk.version !== 'string') {
+    return [pin('global-json', '.NET SDK', 'global.json', 'invalid', null, 'sdk.version is not a string.')];
+  }
+  return [configured('global-json', '.NET SDK', 'global.json', data.sdk.version)];
+}
+
+function toolVersions(text) {
+  const pins = [];
+  const used = new Set();
+  let bad = false;
+  for (const raw of stripBom(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const gap = line.search(/\s/);
+    const name = (gap === -1 ? line : line.slice(0, gap)).toLowerCase();
+    const known = TOOL_VERSIONS[name];
+    if (!known) continue;
+    const version = gap === -1 ? '' : line.slice(gap).trim();
+    if (!version) bad = true;
+    else {
+      let id = known[0];
+      let n = 2;
+      while (used.has(id)) id = `${known[0]}-${n++}`;
+      used.add(id);
+      pins.push(configured(id, known[1], '.tool-versions', version));
+    }
+  }
+  if (bad) return [pin('tool-versions', '.tool-versions', '.tool-versions', 'invalid', null, '.tool-versions has a line that could not be read.')];
+  return pins;
+}
+
+const PARSERS = {
+  '.nvmrc': (text) => textPin('nvmrc', 'Node.js', '.nvmrc', text),
+  '.node-version': (text) => textPin('node-version', 'Node.js', '.node-version', text),
+  '.python-version': (text) => textPin('python-version', 'Python', '.python-version', text),
+  'package.json': packagePins,
+  'pyproject.toml': pythonRequires,
+  'rust-toolchain.toml': rustToml,
+  'rust-toolchain': rustFile,
+  'go.mod': goMod,
+  'global.json': globalJson,
+  '.tool-versions': toolVersions,
+};
+
+function inside(file, root) {
+  const child = path.resolve(file);
+  const base = path.resolve(root);
+  const left = process.platform === 'win32' ? child.toLowerCase() : child;
+  const right = process.platform === 'win32' ? base.toLowerCase() : base;
+  return left.startsWith(right.endsWith(path.sep) ? right : right + path.sep);
+}
+
+const FILE_LABELS = {
+  '.nvmrc': 'Node.js', '.node-version': 'Node.js', '.python-version': 'Python', 'package.json': 'package.json',
+  'pyproject.toml': 'Python', 'rust-toolchain.toml': 'Rust', 'rust-toolchain': 'Rust', 'go.mod': 'Go',
+  'global.json': '.NET SDK', '.tool-versions': '.tool-versions',
+};
+
+function readPin(file, realRoot) {
+  const name = path.basename(file);
+  const label = FILE_LABELS[name] || name;
+  let listed;
+  try { listed = fs.lstatSync(file); } catch (err) {
+    if (err.code === 'ENOENT') return { identity: { name, state: 'absent' } };
+    return { identity: { name, state: 'rejected' }, failure: pin(name, label, name, 'unreadable', null, 'The pin file could not be read.') };
+  }
+  let real = file;
+  if (listed.isSymbolicLink()) {
+    try { real = fs.realpathSync(file); } catch {
+      return { identity: { name, state: 'rejected' }, failure: pin(name, label, name, 'unreadable', null, 'The pin file could not be read.') };
+    }
+    if (!inside(real, realRoot)) {
+      return { identity: { name, state: 'rejected' }, failure: pin(name, label, name, 'unreadable', null, 'The pin is outside the project folder.') };
+    }
+  }
+  let stat;
+  try { stat = fs.statSync(real); } catch {
+    return { identity: { name, state: 'rejected' }, failure: pin(name, label, name, 'unreadable', null, 'The pin file could not be read.') };
+  }
+  if (!stat.isFile()) {
+    return { identity: { name, state: 'rejected' }, failure: pin(name, label, name, 'unreadable', null, 'The pin is not a file.') };
+  }
+  if (stat.size > PIN_LIMIT) {
+    return { identity: { name, state: 'file', mtimeMs: stat.mtimeMs, size: stat.size }, failure: pin(name, label, name, 'unreadable', null, 'The pin file is larger than 64 KiB.') };
+  }
+  return { identity: { name, state: 'file', mtimeMs: stat.mtimeMs, size: stat.size }, file: real };
+}
+
+/** Pins and file identity for one project folder. Does not change the process working directory. */
+export function scanPins(cwd, { identityOnly = false } = {}) {
+  if (typeof cwd !== 'string' || !path.isAbsolute(cwd)) return { error: 'Could not read the project pins.' };
+  let root;
+  try { root = fs.statSync(cwd); } catch { return { error: 'Could not read the project pins.' }; }
+  if (!root.isDirectory()) return { error: 'Could not read the project pins.' };
+  let realRoot;
+  try { realRoot = fs.realpathSync(cwd); } catch { return { error: 'Could not read the project pins.' }; }
+  const identity = [];
+  const pins = [];
+  for (const name of PIN_NAMES) {
+    const read = readPin(path.join(cwd, name), realRoot);
+    identity.push(read.identity);
+    if (identityOnly) continue;
+    if (read.failure) pins.push(read.failure);
+    else if (read.file) {
+      let text;
+      try { text = fs.readFileSync(read.file); } catch {
+        pins.push(pin(name, FILE_LABELS[name] || name, name, 'unreadable', null, 'The pin file could not be read.'));
+        continue;
+      }
+      if (text.length > PIN_LIMIT) {
+        pins.push(pin(name, FILE_LABELS[name] || name, name, 'unreadable', null, 'The pin file is larger than 64 KiB.'));
+        continue;
+      }
+      pins.push(...PARSERS[name](text.toString('utf8')));
+    }
+  }
+  return { identity: JSON.stringify(identity), ...(identityOnly ? {} : { pins }), cwd: process.cwd() };
+}
+
+/** A working folder for a project check. Empty input is refused and does not become the home directory. */
+export function resolveProjectCwd(cwd, { homedir = os.homedir, stat = fs.statSync } = {}) {
+  if (typeof cwd !== 'string' || !cwd.trim()) {
+    throw Object.assign(new Error('A working folder is required.'), { status: 400, code: 'cwd_required' });
+  }
+  let dir = cwd.trim();
+  if (dir === '~' || dir.startsWith('~/') || dir.startsWith('~\\')) dir = path.join(homedir(), dir.slice(1));
+  dir = path.resolve(dir);
+  let info;
+  try { info = stat(dir); } catch {
+    throw Object.assign(new Error(`working directory does not exist: ${dir}`), { status: 400, code: 'bad_cwd' });
+  }
+  if (!info.isDirectory()) throw Object.assign(new Error(`working directory is not a folder: ${dir}`), { status: 400, code: 'bad_cwd' });
+  return dir;
+}

package/src/manager/environment-probe.mjs

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { resolveCommand, killWindowsTree } from './command-resolver.mjs';
+import { scanPins } from './environment-pins.mjs';
 
 export const RUNTIMES = [
   { id: 'node', label: 'Node.js', command: 'node', args: ['--version'], pattern: /^v(\d+\.\d+\.\d+(?:-[\w.-]+)?)\s*$/m },
@@ -52,8 +53,8 @@ export function passiveExecutable(file, id, { platform = process.platform, env =
   if (/\/(?:shims|\.nodejs)\//.test(normalized) || /\/(?:mise|asdf|volta)(?:\.exe)?$/.test(normalized)) {
     return { error: 'A version-manager shim was found. Its runtime cannot be checked without activating the manager.' };
   }
-  if (platform === 'win32' && /\/windowsapps\//.test(normalized)) {
-    return { error: 'A Windows execution alias was found. A runtime behind this alias has not been verified.' };
+  if (platform === 'win32' && windowsAlias(normalized)) {
+    return { error: WINDOWS_ALIAS };
   }
   const head = read(real);
   const binary = head[0] === 0x4d && head[1] === 0x5a // PE
@@ -68,22 +69,43 @@ export function passiveExecutable(file, id, { platform = process.platform, env =
   return { error: 'A script launcher was found. Passive detection does not execute unrecognized wrappers.' };
 }
 
+const WINDOWS_ALIAS = 'A Windows execution alias was found. A runtime behind this alias has not been verified.';
+
+function windowsAlias(file) {
+  return /[\\/]windowsapps[\\/]/i.test(file);
+}
+
 // The helper has a second, independent overall deadline in Environment. A
 // timeout here resolves immediately, even if a descendant retains stdout.
-export function runProbe(file, args, { env, cwd, timeoutMs = TIMEOUT_MS, spawnProcess = spawn } = {}) {
+// The kill is recorded for directory cleanup and does not delay this result.
+export function runProbe(file, args, { env, cwd, timeoutMs = TIMEOUT_MS, spawnProcess = spawn, kills = null } = {}) {
   return new Promise((resolve) => {
     let child, timer, size = 0, output = '', settled = false;
     const stop = () => {
       if (!child?.pid) return;
-      if (process.platform === 'win32') killWindowsTree(child.pid);
-      else { try { child.kill('SIGKILL'); } catch { /* already gone */ } }
-      child.stdout?.destroy(); child.stderr?.destroy(); child.unref();
+      const pending = new Promise((done) => {
+        let ended = false;
+        // Keep cleanup alive after the child is unref'd, even if 'close' never arrives.
+        const backup = setTimeout(finishKill, 2000);
+        function finishKill() {
+          if (ended) return;
+          ended = true;
+          clearTimeout(backup);
+          done();
+        }
+        // 'close' waits for the process to end. Do not settle when stdio is only destroyed.
+        child.once('close', finishKill);
+        if (process.platform === 'win32') killWindowsTree(child.pid, finishKill);
+        else { try { child.kill('SIGKILL'); } catch { finishKill(); } }
+      });
+      if (Array.isArray(kills)) kills.push(pending);
+      try { child.stdout?.destroy(); child.stderr?.destroy(); child.unref(); } catch { /* the kill is already recorded */ }
     };
     const finish = (result, kill = false) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
-      if (kill) stop();
+      if (kill) try { stop(); } catch { /* the probe result still stands */ }
       resolve({ output, ...result });
     };
     try {
@@ -108,17 +130,28 @@ const unavailable = {
   rust: /no default is configured|toolchain .*not installed|could not choose a version|toolchain .*is not installable/i,
 };
 
-export async function scanRuntime(definition, { env, cwd, platform = process.platform, resolve = resolveCommand, inspect = passiveExecutable, run = runProbe } = {}) {
+export async function scanRuntime(definition, { env, cwd, platform = process.platform, resolve = resolveCommand, inspect = passiveExecutable, run = runProbe, kills = null } = {}) {
   const { id, label, command, args, pattern } = definition;
   const base = { id, label, status: 'not_found', version: null, path: null, command, detail: null };
   const one = async (name) => {
-    const file = resolve(name, env, platform);
-    if (!file) return { ...base, command: name };
+    // A Windows execution alias must not be inspected or spawned. A later real binary still wins.
+    let alias = null;
+    const file = resolve(name, env, platform, {
+      onSkip(candidate) {
+        if (platform !== 'win32' || !windowsAlias(candidate)) return false;
+        if (!alias || path.win32.extname(candidate).toLowerCase() === '.exe') alias = candidate;
+        return true;
+      },
+    });
+    if (!file) {
+      if (!alias) return { ...base, command: name };
+      return { ...base, command: name, path: alias, status: 'unavailable', detail: WINDOWS_ALIAS };
+    }
     const row = { ...base, command: name, path: file };
     try {
       const executable = inspect(file, id, { platform, env });
       if (executable.error) return { ...row, status: 'unavailable', detail: executable.error };
-      const result = await run(executable.file, args, { env: { ...probeEnv(env), DOTNET_CLI_HOME: cwd, DOTNET_GENERATE_ASPNET_CERTIFICATE: 'false' }, cwd });
+      const result = await run(executable.file, args, { env: { ...probeEnv(env), DOTNET_CLI_HOME: cwd, DOTNET_GENERATE_ASPNET_CERTIFICATE: 'false' }, cwd, kills });
       if (result.error) return { ...row, status: 'failed', detail: result.error };
       const version = result.code === 0 ? pattern.exec(result.output)?.[1] : null;
       if (version) return { ...row, status: 'ok', version };
@@ -139,7 +172,7 @@ export async function scanRuntime(definition, { env, cwd, platform = process.pla
     try {
       const executable = inspect(row.path, id, { platform, env });
       if (!executable.error) {
-        const result = await run(executable.file, ['--list-runtimes'], { env: { ...probeEnv(env), DOTNET_CLI_HOME: cwd }, cwd });
+        const result = await run(executable.file, ['--list-runtimes'], { env: { ...probeEnv(env), DOTNET_CLI_HOME: cwd }, cwd, kills });
         if (result.code === 0) row.runtimes = result.output.split(/\r?\n/).map((line) => line.match(/^(Microsoft\.[\w.]+) (\d+\.\d+\.\d+(?:-[\w.-]+)?) \[/))
           .filter(Boolean).map((match) => ({ name: match[1], version: match[2] }));
       }
@@ -162,10 +195,41 @@ export function detectTools({ env, platform = process.platform, resolve = resolv
   return tools;
 }
 
+// Windows cannot remove a process's current working directory, and a probe
+// killed at its deadline can still hold that directory. Cleanup must not
+// decide whether the scan succeeded.
+export async function releaseScanDirectory(cwd, kills = [], {
+  chdir = (dir) => process.chdir(dir),
+  remove = fs.rmSync,
+  tmpdir = os.tmpdir,
+} = {}) {
+  await Promise.all(kills).catch(() => {});
+  let temp = '';
+  try { temp = tmpdir(); } catch { /* removal is skipped below */ }
+  try { if (temp) chdir(temp); } catch { /* still try to remove the scan directory */ }
+  if (!cwd || !temp) return;
+  if (path.dirname(cwd) !== path.resolve(temp) || !path.basename(cwd).startsWith('agent-guild-environment-')) return;
+  try {
+    remove(cwd, { recursive: true, force: true, maxRetries: 5, retryDelay: 40 });
+  } catch { /* a leftover lock must not fail the scan */ }
+}
+
+if ((process.argv[2] === '--scan-pins' || process.argv[2] === '--pin-identity') && process.send) {
+  // Read the named folder by absolute path. Never chdir into it: a project
+  // directory can activate tools on entry, and this check must not.
+  const started = process.cwd();
+  const result = scanPins(process.argv[3], { identityOnly: process.argv[2] === '--pin-identity' });
+  process.send({ ...result, cwd: process.cwd() });
+  if (process.cwd() !== started) process.chdir(started);
+  process.send({ done: true });
+}
+
 if (process.argv[2] === '--scan-environment' && process.send) {
   // A fresh temporary directory contains no project files. Manager env is
   // retained; no selected shell, project or session is inspected or changed.
   let cwd;
+  let finished = false;
+  const kills = [];
   try {
     cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-guild-environment-'));
     process.chdir(cwd);
@@ -174,16 +238,13 @@ if (process.argv[2] === '--scan-environment' && process.send) {
     // Two batches bound concurrency while giving each runtime its own result.
     for (let i = 0; i < RUNTIMES.length; i += 3) {
       await Promise.all(RUNTIMES.slice(i, i + 3).map(async (definition) => {
-        const runtime = await scanRuntime(definition, { env, cwd });
+        const runtime = await scanRuntime(definition, { env, cwd, kills });
         process.send({ runtime });
       }));
     }
+    finished = true;
   } finally {
-    // Windows cannot remove a process's current working directory.
-    process.chdir(os.tmpdir());
-    if (cwd && path.dirname(cwd) === path.resolve(os.tmpdir()) && path.basename(cwd).startsWith('agent-guild-environment-')) {
-      fs.rmSync(cwd, { recursive: true, force: true });
-    }
+    await releaseScanDirectory(cwd, kills);
   }
-  process.send({ done: true });
+  if (finished) process.send({ done: true });
 }