agentic-workflow-manager 6.5.2 → 8.1.0

package/dist/src/commands/sensors/compatibility/contract.js

@@ -0,0 +1,382 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSemgrepPolicy = parseSemgrepPolicy;
+exports.resolveSemgrepPolicy = resolveSemgrepPolicy;
+exports.parseStructuredCommand = parseStructuredCommand;
+exports.assertNoEqualPriorityOverlap = assertNoEqualPriorityOverlap;
+exports.parseSensorPack = parseSensorPack;
+const semver_1 = __importDefault(require("semver"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const contract_1 = require("../coverage/contract");
+const PACK_SCHEMA_VERSION = 2;
+const SHELL_EXECUTABLES = new Set(['sh', 'bash', 'cmd', 'powershell']);
+const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
+const ALLOWED_PROBES = new Set([
+    'version',
+    'eslint-print-config',
+    'typescript-show-config',
+    'semgrep-validate',
+    'package-script-present',
+    'config-present',
+]);
+function normalizedPackageManager(value) {
+    return value.toLowerCase().replace(/\.exe$/, '');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function sourceSuffix(source) {
+    return typeof source === 'string' && source.length > 0 && !/[\0\r\n]/.test(source) ? ` in ${source}` : ' in <unknown source>';
+}
+function invalid(source, message) {
+    throw new Error(`Invalid sensor pack${sourceSuffix(source)}: ${message}`);
+}
+function record(value, source, location) {
+    if (!isRecord(value))
+        invalid(source, `${location} must be an object`);
+    return value;
+}
+function fields(value, allowed, source, location) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            invalid(source, `${location} has unknown field "${key}"`);
+    }
+}
+function text(value, source, location) {
+    if (typeof value !== 'string' || value.trim().length === 0 || /[\0\r\n]/.test(value)) {
+        invalid(source, `${location} must be a nonempty single-line string without NUL`);
+    }
+    return value;
+}
+function id(value, source, location) {
+    const parsed = text(value, source, location);
+    if (!/^[a-z][a-z0-9-]*$/.test(parsed))
+        invalid(source, `${location} must be a stable lowercase id`);
+    return parsed;
+}
+function asset(value, source, location) {
+    const parsed = text(value, source, location);
+    if (parsed.startsWith('/') || /^[A-Za-z]:[\\/]/.test(parsed) || parsed.startsWith('\\\\') || parsed.includes('\\') || parsed.split('/').some(part => part === '' || part === '.' || part === '..')) {
+        invalid(source, `${location} must be a contained relative asset path`);
+    }
+    return parsed;
+}
+function stringArray(value, source, location) {
+    if (!Array.isArray(value) || value.length === 0)
+        invalid(source, `${location} must be a nonempty array`);
+    return value.map((item, index) => text(item, source, `${location}[${index}]`));
+}
+function assetArray(value, source, location, allowEmpty = false) {
+    if (!Array.isArray(value) || (!allowEmpty && value.length === 0))
+        invalid(source, `${location} must be a ${allowEmpty ? '' : 'nonempty '}array`);
+    return value.map((item, index) => asset(item, source, `${location}[${index}]`));
+}
+const SEMGREP_POLICY_REF = 'shared/semgrep-policy.json';
+const MAX_POLICY_BYTES = 64 * 1024;
+function contained(root, candidate) {
+    const prefix = root.endsWith(path_1.default.sep) ? root : root + path_1.default.sep;
+    return candidate.startsWith(prefix);
+}
+function parseSemgrepPolicy(input, source) {
+    const value = record(input, source, 'Semgrep policy');
+    fields(value, ['tool', 'toolRange', 'runtime', 'runtimeRange', 'probe'], source, 'Semgrep policy');
+    if (value.tool !== 'semgrep' || value.runtime !== 'python' || value.probe !== 'semgrep-validate') {
+        invalid(source, 'Semgrep policy must declare semgrep, python, and semgrep-validate');
+    }
+    const toolRange = text(value.toolRange, source, 'Semgrep policy.toolRange');
+    const runtimeRange = text(value.runtimeRange, source, 'Semgrep policy.runtimeRange');
+    if (semver_1.default.validRange(toolRange) === null || semver_1.default.validRange(runtimeRange) === null)
+        invalid(source, 'Semgrep policy ranges must be valid semver ranges');
+    return { tool: 'semgrep', toolRange, runtime: 'python', runtimeRange, probe: 'semgrep-validate' };
+}
+function resolveSemgrepPolicy(policyRef, source, location = 'policy') {
+    if (policyRef !== SEMGREP_POLICY_REF)
+        invalid(source, `${location}.policyRef must be the contained AWM-owned ${SEMGREP_POLICY_REF}`);
+    if (typeof source !== 'string' || !path_1.default.isAbsolute(source) || path_1.default.normalize(source) !== source || path_1.default.basename(source) !== 'pack.json') {
+        invalid(source, `${location}.policyRef requires an absolute pack.json source`);
+    }
+    const packRoot = path_1.default.dirname(source);
+    const sensorPacksRoot = path_1.default.dirname(packRoot);
+    const candidate = path_1.default.join(sensorPacksRoot, ...SEMGREP_POLICY_REF.split('/'));
+    if (!contained(sensorPacksRoot, candidate))
+        invalid(source, `${location}.policyRef escapes sensor-packs root`);
+    let stat;
+    try {
+        stat = fs_1.default.lstatSync(candidate);
+    }
+    catch {
+        invalid(source, `${location}.policyRef does not resolve to a regular policy file`);
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_POLICY_BYTES)
+        invalid(source, `${location}.policyRef must resolve to a bounded regular policy file`);
+    let realRoot;
+    let realPolicy;
+    try {
+        realRoot = fs_1.default.realpathSync(sensorPacksRoot);
+        realPolicy = fs_1.default.realpathSync(candidate);
+    }
+    catch {
+        invalid(source, `${location}.policyRef cannot be canonicalized`);
+    }
+    if (!contained(realRoot, realPolicy))
+        invalid(source, `${location}.policyRef escapes sensor-packs root`);
+    let parsed;
+    try {
+        parsed = JSON.parse(fs_1.default.readFileSync(realPolicy, 'utf8'));
+    }
+    catch {
+        invalid(source, `${location}.policyRef must contain valid JSON`);
+    }
+    return parseSemgrepPolicy(parsed, realPolicy);
+}
+function parseStructuredCommand(input, source) {
+    const value = record(input, source, 'command');
+    fields(value, ['executable', 'resolution', 'args', 'packageManager', 'environment', 'fileInput', 'pythonEnvironmentRoot'], source, 'command');
+    const executable = text(value.executable, source, 'command.executable');
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(executable) || SHELL_EXECUTABLES.has(executable.toLowerCase().replace(/\.exe$/, ''))) {
+        invalid(source, 'command.executable must not be a shell or path');
+    }
+    if (value.resolution !== 'node-modules-bin' && value.resolution !== 'python-environment' && value.resolution !== 'path') {
+        invalid(source, 'command.resolution must be a supported resolution');
+    }
+    const args = stringArray(value.args, source, 'command.args');
+    for (const [index, arg] of args.entries()) {
+        if (arg.includes('{files}') && arg !== '{files}')
+            invalid(source, `command.args[${index}] must not embed {files}`);
+    }
+    const command = { executable, resolution: value.resolution, args };
+    if ('pythonEnvironmentRoot' in value) {
+        if (value.resolution !== 'python-environment' || (value.pythonEnvironmentRoot !== '.venv' && value.pythonEnvironmentRoot !== 'venv'))
+            invalid(source, 'command.pythonEnvironmentRoot must name the selected .venv or venv Python environment');
+        command.pythonEnvironmentRoot = value.pythonEnvironmentRoot;
+    }
+    const executablePackageManager = normalizedPackageManager(executable);
+    if (PACKAGE_MANAGERS.has(executablePackageManager) && !('packageManager' in value))
+        invalid(source, 'command.packageManager is required for a package-manager executable');
+    if ('packageManager' in value) {
+        if (typeof value.packageManager !== 'string' || !PACKAGE_MANAGERS.has(normalizedPackageManager(value.packageManager)))
+            invalid(source, 'command.packageManager must be npm, pnpm, yarn, or bun');
+        const packageManager = normalizedPackageManager(value.packageManager);
+        if (packageManager !== executablePackageManager)
+            invalid(source, 'command.packageManager must match executable');
+        command.packageManager = packageManager;
+    }
+    if ('environment' in value) {
+        const environment = record(value.environment, source, 'command.environment');
+        fields(environment, ['ESLINT_USE_FLAT_CONFIG'], source, 'command.environment');
+        if ((environment.ESLINT_USE_FLAT_CONFIG !== 'true' && environment.ESLINT_USE_FLAT_CONFIG !== 'false') || Object.keys(environment).length !== 1)
+            invalid(source, 'command.environment must be the exact allowlisted ESLINT_USE_FLAT_CONFIG=true or false mapping');
+        command.environment = { ESLINT_USE_FLAT_CONFIG: environment.ESLINT_USE_FLAT_CONFIG };
+    }
+    if ('fileInput' in value) {
+        const fileInput = record(value.fileInput, source, 'command.fileInput');
+        fields(fileInput, ['placeholder', 'extensions'], source, 'command.fileInput');
+        if (fileInput.placeholder !== '{files}')
+            invalid(source, 'command.fileInput.placeholder must be {files}');
+        const extensions = stringArray(fileInput.extensions, source, 'command.fileInput.extensions');
+        for (const [index, extension] of extensions.entries()) {
+            if (!/^\.[A-Za-z0-9]+$/.test(extension))
+                invalid(source, `command.fileInput.extensions[${index}] must be an extension`);
+        }
+        if (args.filter(arg => arg === '{files}').length !== 1)
+            invalid(source, 'command.fileInput requires exactly one {files} argument');
+        command.fileInput = { placeholder: '{files}', extensions };
+    }
+    else if (args.includes('{files}')) {
+        invalid(source, 'command {files} argument requires fileInput');
+    }
+    return command;
+}
+function parseVariant(input, source, location) {
+    const value = record(input, source, location);
+    fields(value, ['id', 'priority', 'requirements', 'certifiedRange', 'command', 'assets', 'formatter', 'probe', 'policyRef'], source, location);
+    const certifiedRange = text(value.certifiedRange, source, `${location}.certifiedRange`);
+    if (semver_1.default.validRange(certifiedRange) === null)
+        invalid(source, `${location}.certifiedRange must be a valid semver range`);
+    if (typeof value.priority !== 'number' || !Number.isSafeInteger(value.priority))
+        invalid(source, `${location}.priority must be a safe integer`);
+    const policy = 'policyRef' in value ? resolveSemgrepPolicy(value.policyRef, source, location) : undefined;
+    if (policy && ('requirements' in value || 'probe' in value))
+        invalid(source, `${location}.policyRef is authoritative; requirements and probe must not duplicate it`);
+    if (!policy && (!('requirements' in value) || !('probe' in value)))
+        invalid(source, `${location} requires requirements and probe when policyRef is absent`);
+    const requirements = policy ? undefined : record(value.requirements, source, `${location}.requirements`);
+    if (requirements)
+        fields(requirements, ['tool', 'toolRange', 'runtime', 'runtimeRange', 'configFiles'], source, `${location}.requirements`);
+    const toolRange = policy?.toolRange ?? text(requirements.toolRange, source, `${location}.requirements.toolRange`);
+    const runtimeRange = policy?.runtimeRange ?? text(requirements.runtimeRange, source, `${location}.requirements.runtimeRange`);
+    if (semver_1.default.validRange(toolRange) === null || semver_1.default.validRange(runtimeRange) === null)
+        invalid(source, `${location}.requirements ranges must be valid semver ranges`);
+    const probe = policy ? undefined : record(value.probe, source, `${location}.probe`);
+    if (probe) {
+        fields(probe, ['kind'], source, `${location}.probe`);
+        if (typeof probe.kind !== 'string' || !ALLOWED_PROBES.has(probe.kind))
+            invalid(source, `${location}.probe.kind must be an allowed probe`);
+    }
+    return {
+        id: id(value.id, source, `${location}.id`),
+        priority: value.priority,
+        certifiedRange,
+        requirements: policy
+            ? { tool: policy.tool, toolRange, runtime: policy.runtime, runtimeRange }
+            : { tool: text(requirements.tool, source, `${location}.requirements.tool`), toolRange, runtime: text(requirements.runtime, source, `${location}.requirements.runtime`), runtimeRange, ...('configFiles' in requirements ? { configFiles: stringArray(requirements.configFiles, source, `${location}.requirements.configFiles`).map((file, index) => asset(file, source, `${location}.requirements.configFiles[${index}]`)) } : {}) },
+        assets: assetArray(value.assets, source, `${location}.assets`, true),
+        formatter: text(value.formatter, source, `${location}.formatter`),
+        probe: { kind: policy?.probe ?? probe.kind },
+        ...(policy ? { policyRef: SEMGREP_POLICY_REF } : {}),
+        command: parseStructuredCommand(value.command, source),
+    };
+}
+function parseHardening(input, source) {
+    const value = record(input, source, 'hardening');
+    const names = Object.keys(value);
+    if (names.length === 0)
+        invalid(source, 'hardening must be nonempty when declared');
+    const hardening = {};
+    for (const name of names) {
+        const entry = record(value[name], source, `hardening.${name}`);
+        fields(entry, ['assets'], source, `hardening.${name}`);
+        hardening[id(name, source, 'hardening id')] = { assets: assetArray(entry.assets, source, `hardening.${name}.assets`) };
+    }
+    return hardening;
+}
+function assertNoEqualPriorityOverlapParsed(parsed) {
+    for (let left = 0; left < parsed.length; left++) {
+        const first = parsed[left];
+        for (let right = left + 1; right < parsed.length; right++) {
+            const second = parsed[right];
+            const toolRangesIntersect = semver_1.default.intersects(first.requirements.toolRange, second.requirements.toolRange);
+            const runtimeRangesIntersect = semver_1.default.intersects(first.requirements.runtimeRange, second.requirements.runtimeRange);
+            if (first.priority === second.priority && toolRangesIntersect && runtimeRangesIntersect) {
+                throw new Error(`variants "${first.id}" and "${second.id}" overlap at priority ${first.priority}`);
+            }
+        }
+    }
+}
+function assertNoEqualPriorityOverlap(variants) {
+    if (!Array.isArray(variants) || variants.length === 0)
+        throw new Error('variants must be a nonempty array');
+    assertNoEqualPriorityOverlapParsed(variants.map((variant, index) => parseVariant(variant, 'public overlap validator', `variants[${index}]`)));
+}
+function parseSensor(input, source, location, variantIds) {
+    const value = record(input, source, location);
+    fields(value, ['applicability', 'variants', 'fast'], source, location);
+    if (!Array.isArray(value.variants) || value.variants.length === 0)
+        invalid(source, `${location}.variants must be a nonempty array`);
+    const variants = value.variants.map((variant, index) => parseVariant(variant, source, `${location}.variants[${index}]`));
+    for (const variant of variants) {
+        if (variantIds.has(variant.id))
+            invalid(source, `variant id "${variant.id}" must be unique`);
+        variantIds.add(variant.id);
+    }
+    try {
+        assertNoEqualPriorityOverlapParsed(variants);
+    }
+    catch (error) {
+        invalid(source, `${location}.variants ${error instanceof Error ? error.message : 'overlap validation failed'}`);
+    }
+    const applicabilityInput = record(value.applicability, source, `${location}.applicability`);
+    fields(applicabilityInput, ['allFiles', 'anyFiles', 'kind'], source, `${location}.applicability`);
+    const applicability = {};
+    if ('allFiles' in applicabilityInput)
+        applicability.allFiles = stringArray(applicabilityInput.allFiles, source, `${location}.applicability.allFiles`).map((file, index) => asset(file, source, `${location}.applicability.allFiles[${index}]`));
+    if ('anyFiles' in applicabilityInput)
+        applicability.anyFiles = stringArray(applicabilityInput.anyFiles, source, `${location}.applicability.anyFiles`).map((file, index) => asset(file, source, `${location}.applicability.anyFiles[${index}]`));
+    if ('kind' in applicabilityInput)
+        applicability.kind = text(applicabilityInput.kind, source, `${location}.applicability.kind`);
+    if (Object.keys(applicability).length === 0)
+        invalid(source, `${location}.applicability must declare a condition`);
+    if ('fast' in value && typeof value.fast !== 'boolean')
+        invalid(source, `${location}.fast must be a boolean`);
+    return { applicability, variants, ...('fast' in value ? { fast: value.fast } : {}) };
+}
+function legacyCompatibility() {
+    return {
+        state: 'compatible-unverified',
+        reason: 'legacy pack without schemaVersion',
+        variantId: null,
+        toolVersion: null,
+        runtimeVersion: null,
+        certifiedRange: null,
+        evidence: [],
+    };
+}
+function parseLegacyPack(value, source) {
+    fields(value, ['name', 'description', 'detects', 'sensors', 'coverage'], source, 'root');
+    const name = id(value.name, source, 'name');
+    const sensorsInput = record(value.sensors, source, 'sensors');
+    const sensors = {};
+    for (const sensorName of Object.keys(sensorsInput)) {
+        const sensor = record(sensorsInput[sensorName], source, `sensors.${sensorName}`);
+        fields(sensor, ['defaultCmd', 'fast', 'enabled', 'changedCmd', 'changedExtensions', 'formatter', 'configFile', 'configFileFallback'], source, `sensors.${sensorName}`);
+        const parsed = {};
+        if ('defaultCmd' in sensor)
+            parsed.defaultCmd = text(sensor.defaultCmd, source, `sensors.${sensorName}.defaultCmd`);
+        if ('fast' in sensor) {
+            if (typeof sensor.fast !== 'boolean')
+                invalid(source, `sensors.${sensorName}.fast must be a boolean`);
+            parsed.fast = sensor.fast;
+        }
+        if ('enabled' in sensor) {
+            if (typeof sensor.enabled !== 'boolean')
+                invalid(source, `sensors.${sensorName}.enabled must be a boolean`);
+            parsed.enabled = sensor.enabled;
+        }
+        if ('changedCmd' in sensor)
+            parsed.changedCmd = text(sensor.changedCmd, source, `sensors.${sensorName}.changedCmd`);
+        if ('changedExtensions' in sensor)
+            parsed.changedExtensions = stringArray(sensor.changedExtensions, source, `sensors.${sensorName}.changedExtensions`);
+        if ('formatter' in sensor)
+            parsed.formatter = text(sensor.formatter, source, `sensors.${sensorName}.formatter`);
+        if ('configFile' in sensor)
+            parsed.configFile = asset(sensor.configFile, source, `sensors.${sensorName}.configFile`);
+        if ('configFileFallback' in sensor)
+            parsed.configFileFallback = asset(sensor.configFileFallback, source, `sensors.${sensorName}.configFileFallback`);
+        sensors[id(sensorName, source, 'sensor id')] = parsed;
+    }
+    const legacy = { name, sensors, compatibility: legacyCompatibility() };
+    if ('description' in value)
+        legacy.description = text(value.description, source, 'description');
+    if ('detects' in value) {
+        if (!Array.isArray(value.detects))
+            invalid(source, 'detects must be an array');
+        legacy.detects = value.detects.map((detect, index) => text(detect, source, `detects[${index}]`));
+    }
+    if ('coverage' in value)
+        legacy.coverage = (0, contract_1.parseCoverageContract)(value.coverage, source);
+    return legacy;
+}
+function parseSensorPack(input, source) {
+    const value = record(input, source, 'root');
+    if (!('schemaVersion' in value))
+        return { kind: 'legacy', pack: parseLegacyPack(value, source) };
+    fields(value, ['schemaVersion', 'name', 'description', 'detects', 'sensors', 'coverage', 'hardening'], source, 'root');
+    if (value.schemaVersion !== PACK_SCHEMA_VERSION)
+        invalid(source, `unsupported pack schemaVersion ${String(value.schemaVersion)}; supported: legacy, 2; upgrade or migrate the pack`);
+    const sensorsInput = record(value.sensors, source, 'sensors');
+    const sensorNames = Object.keys(sensorsInput);
+    if (sensorNames.length === 0)
+        invalid(source, 'sensors must be nonempty');
+    const sensors = {};
+    const variantIds = new Set();
+    for (const name of sensorNames)
+        sensors[id(name, source, 'sensor id')] = parseSensor(sensorsInput[name], source, `sensors.${name}`, variantIds);
+    let coverage;
+    try {
+        coverage = (0, contract_1.parseCoverageContract)(value.coverage, source);
+    }
+    catch (error) {
+        invalid(source, `coverage.${error instanceof Error ? error.message.replace(/^.*?: /, '') : 'is invalid'}`);
+    }
+    const hardening = 'hardening' in value ? parseHardening(value.hardening, source) : undefined;
+    return { kind: 'v2', pack: {
+            schemaVersion: PACK_SCHEMA_VERSION,
+            name: id(value.name, source, 'name'), description: text(value.description, source, 'description'), detects: stringArray(value.detects, source, 'detects'),
+            sensors, ...(hardening ? { hardening } : {}),
+            coverage,
+        } };
+}

package/dist/src/commands/sensors/compatibility/discovery.js

@@ -0,0 +1,207 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverProjectEvidence = discoverProjectEvidence;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const semver_1 = __importDefault(require("semver"));
+const paths_1 = require("../../../core/paths");
+const LOCKFILES = { 'package-lock.json': 'npm', 'npm-shrinkwrap.json': 'npm', 'pnpm-lock.yaml': 'pnpm', 'yarn.lock': 'yarn', 'bun.lockb': 'bun', 'bun.lock': 'bun' };
+const COMMON_CONFIGS = ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs', '.eslintrc', '.eslintrc.json', 'tsconfig.json', 'semgrep.yml', 'semgrep.yaml', '.semgrep.yml', 'pyproject.toml', 'ruff.toml', 'mypy.ini', 'setup.cfg'];
+function safeFile(root, relative) {
+    if (!relative || path_1.default.isAbsolute(relative) || relative.includes('\\') || relative.split('/').some(part => part === '.' || part === '..' || part === ''))
+        return false;
+    try {
+        const stat = fs_1.default.lstatSync(path_1.default.join(root, relative));
+        return stat.isFile() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function safeParts(parts) {
+    return parts.length > 0 && parts.every(part => Boolean(part) && part !== '.' && part !== '..' && !part.includes('/') && !part.includes('\\'));
+}
+/** Refuse every symlink in a local environment path; evidence must never escape cwd. */
+function containedEntry(root, parts, expect) {
+    if (!safeParts(parts))
+        return null;
+    let candidate = root;
+    try {
+        for (const part of parts) {
+            candidate = path_1.default.join(candidate, part);
+            const stat = fs_1.default.lstatSync(candidate);
+            if (stat.isSymbolicLink())
+                return null;
+        }
+        const stat = fs_1.default.lstatSync(candidate);
+        return (expect === 'file' ? stat.isFile() : stat.isDirectory()) ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readBoundedLocalFile(root, parts) {
+    const file = containedEntry(root, parts, 'file');
+    if (!file)
+        return null;
+    try {
+        const stat = fs_1.default.statSync(file);
+        return stat.size <= 64 * 1024 ? fs_1.default.readFileSync(file, 'utf8') : null;
+    }
+    catch {
+        return null;
+    }
+}
+function exactVersion(value) {
+    return typeof value === 'string' && semver_1.default.valid(value.trim()) !== null ? semver_1.default.clean(value.trim()) : null;
+}
+function pythonEnvironment(root) {
+    for (const name of ['.venv', 'venv']) {
+        if (!containedEntry(root, [name], 'directory'))
+            continue;
+        const config = readBoundedLocalFile(root, [name, 'pyvenv.cfg']);
+        const version = config?.match(/^version\s*=\s*([^\r\n#]+)\s*$/mi)?.[1] ?? null;
+        return { rootParts: [name], runtimeVersion: exactVersion(version) };
+    }
+    return null;
+}
+function pythonSitePackages(root, environment, target) {
+    const candidates = target === 'win32'
+        ? [[...environment, 'Lib', 'site-packages']]
+        : [];
+    if (target !== 'win32') {
+        const lib = containedEntry(root, [...environment, 'lib'], 'directory');
+        if (lib) {
+            try {
+                for (const entry of fs_1.default.readdirSync(lib, { withFileTypes: true }).slice(0, 128)) {
+                    if (entry.isDirectory() && !entry.isSymbolicLink() && /^python\d+\.\d+$/.test(entry.name))
+                        candidates.push([...environment, 'lib', entry.name, 'site-packages']);
+                }
+            }
+            catch { /* unreadable environments are not evidence */ }
+        }
+    }
+    return candidates.filter(parts => containedEntry(root, parts, 'directory') !== null);
+}
+function pythonToolVersion(root, sitePackages, tool) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(tool))
+        return null;
+    const normalized = tool.replace(/[._-]+/g, '-').toLowerCase();
+    for (const directory of sitePackages) {
+        const folder = containedEntry(root, directory, 'directory');
+        if (!folder)
+            continue;
+        let entries;
+        try {
+            entries = fs_1.default.readdirSync(folder, { withFileTypes: true }).slice(0, 512);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.isSymbolicLink() || !entry.name.endsWith('.dist-info'))
+                continue;
+            const distribution = entry.name.slice(0, -'.dist-info'.length);
+            if (!distribution.toLowerCase().startsWith(normalized + '-'))
+                continue;
+            const metadata = readBoundedLocalFile(root, [...directory, entry.name, 'METADATA']);
+            if (!metadata)
+                continue;
+            const name = metadata.match(/^Name:\s*([^\r\n]+)\s*$/mi)?.[1]?.trim().replace(/[._-]+/g, '-').toLowerCase();
+            const version = exactVersion(metadata.match(/^Version:\s*([^\r\n]+)\s*$/mi)?.[1]);
+            if (name === normalized && version)
+                return version;
+        }
+    }
+    return null;
+}
+function packageJson(root) {
+    if (!safeFile(root, 'package.json'))
+        return null;
+    try {
+        const parsed = JSON.parse(fs_1.default.readFileSync(path_1.default.join(root, 'package.json'), 'utf8'));
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stringMap(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === 'string'));
+}
+function installedPackageVersion(root, tool) {
+    if (!tool || tool.split('/').some(part => !part || part === '.' || part === '..' || part.includes('\\')))
+        return null;
+    const packageFile = path_1.default.join(root, 'node_modules', ...tool.split('/'), 'package.json');
+    try {
+        const modules = fs_1.default.realpathSync(path_1.default.join(root, 'node_modules'));
+        const fileStat = fs_1.default.lstatSync(packageFile);
+        if (!fileStat.isFile() || fileStat.isSymbolicLink())
+            return null;
+        const real = fs_1.default.realpathSync(packageFile);
+        if (!real.startsWith(modules + path_1.default.sep))
+            return null;
+        const parsed = JSON.parse(fs_1.default.readFileSync(real, 'utf8'));
+        const version = typeof parsed.version === 'string' ? parsed.version : null;
+        return version !== null && semver_1.default.valid(version) !== null ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read bounded project metadata only; it never shells out, downloads, or mutates. */
+function discoverProjectEvidence(cwd, pack, dependencies = {}) {
+    if (typeof cwd !== 'string' || cwd.trim() === '')
+        throw new Error('cwd must be a non-empty path');
+    let root;
+    try {
+        root = fs_1.default.realpathSync(cwd);
+        if (!fs_1.default.statSync(root).isDirectory())
+            throw new Error();
+    }
+    catch {
+        throw new Error(`cwd is not a readable project directory: ${cwd}`);
+    }
+    if (!pack || typeof pack !== 'object' || typeof pack.name !== 'string')
+        throw new Error('pack must be a parsed sensor pack');
+    const targetPlatform = (dependencies.platform ?? paths_1.platform)();
+    const pkg = packageJson(root);
+    const locks = Object.keys(LOCKFILES).filter(file => safeFile(root, file));
+    const lockManagers = new Set(locks.map(file => LOCKFILES[file]));
+    const declaredManager = typeof pkg?.packageManager === 'string' ? pkg.packageManager.split('@')[0] : null;
+    if (declaredManager)
+        lockManagers.add(declaredManager);
+    const configCandidates = new Set(COMMON_CONFIGS);
+    if ('schemaVersion' in pack) {
+        for (const marker of pack.detects)
+            configCandidates.add(marker);
+        for (const sensor of Object.values(pack.sensors)) {
+            for (const marker of [...(sensor.applicability.allFiles ?? []), ...(sensor.applicability.anyFiles ?? [])])
+                configCandidates.add(marker);
+            for (const variant of sensor.variants)
+                for (const config of variant.requirements.configFiles ?? [])
+                    configCandidates.add(config);
+        }
+    }
+    const configFiles = [...configCandidates].filter(file => safeFile(root, file)).sort();
+    const scripts = Object.keys(stringMap(pkg?.scripts)).sort();
+    const declaredToolRanges = { ...stringMap(pkg?.dependencies), ...stringMap(pkg?.devDependencies), ...stringMap(pkg?.peerDependencies) };
+    const tools = new Set();
+    if ('schemaVersion' in pack)
+        for (const sensor of Object.values(pack.sensors))
+            for (const variant of sensor.variants)
+                tools.add(variant.requirements.tool);
+    const environment = pythonEnvironment(root);
+    const sitePackages = environment ? pythonSitePackages(root, environment.rootParts, targetPlatform) : [];
+    const toolVersions = Object.fromEntries([...tools].sort().map(tool => [tool, pythonToolVersion(root, sitePackages, tool) ?? installedPackageVersion(root, tool)]));
+    return {
+        cwd: root, os: targetPlatform, runtimeVersions: { node: process.versions.node ?? null, ...(environment ? { python: environment.runtimeVersion } : {}) }, pythonEnvironmentRoot: environment?.rootParts[0] ?? null, declaredToolRanges, toolVersions,
+        packageManager: declaredManager ?? (lockManagers.size === 1 ? [...lockManagers][0] : null), packageManagerConflict: lockManagers.size > 1,
+        scripts, configFiles, paths: [...new Set([...(safeFile(root, 'package.json') ? ['package.json'] : []), ...locks, ...configFiles])].sort(),
+    };
+}