agentic-workflow-manager 6.5.2 → 8.1.0

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

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLiveCompatibility = resolveLiveCompatibility;
+exports.resolveParsedPackCompatibility = resolveParsedPackCompatibility;
+const pack_source_1 = require("./pack-source");
+const contract_1 = require("./contract");
+const discovery_1 = require("./discovery");
+const resolve_1 = require("./resolve");
+const probe_1 = require("./probe");
+const path_1 = __importDefault(require("path"));
+/**
+ * Python package metadata is evidence only for a contained virtual environment.
+ * A v2 command that names a Python-runtime tool must therefore resolve through
+ * that same environment — never a same-named executable inherited from PATH.
+ *
+ * Keep this at the live pack boundary so the command used by probing, init's
+ * materialized manifest, and `sensors run` is one identical structured command.
+ */
+function containedRuntimeCommand(variant, pythonEnvironmentRoot) {
+    if (variant.requirements.runtime !== 'python')
+        return variant;
+    return {
+        ...variant,
+        command: {
+            ...variant.command,
+            resolution: 'python-environment',
+            ...(pythonEnvironmentRoot ? { pythonEnvironmentRoot } : {}),
+        },
+    };
+}
+function bindContainedRuntimeCommands(pack, pythonEnvironmentRoot) {
+    return {
+        ...pack,
+        sensors: Object.fromEntries(Object.entries(pack.sensors).map(([name, sensor]) => [
+            name,
+            { ...sensor, variants: sensor.variants.map(variant => containedRuntimeCommand(variant, pythonEnvironmentRoot)) },
+        ])),
+    };
+}
+/**
+ * Re-resolve a v2 pack from the configured registry and current project evidence.
+ * Manifest evidence is intentionally not an input: it is an init-time trace, not a
+ * live certification source. Probes are bounded and structured through the shared
+ * compatibility probe runner.
+ */
+async function resolveLiveCompatibility(cwd, packName, registryRoot, options = {}) {
+    if (typeof cwd !== 'string' || cwd.trim() === '')
+        throw new Error('cwd must be a non-empty path');
+    if (typeof packName !== 'string' || !/^[a-z][a-z0-9-]*$/.test(packName))
+        throw new Error('pack name must be a stable lowercase id');
+    if (registryRoot !== undefined && (typeof registryRoot !== 'string' || !path_1.default.isAbsolute(registryRoot) || path_1.default.normalize(registryRoot) !== registryRoot || /[\0\r\n]/.test(registryRoot))) {
+        throw new Error('registry root provenance must be an absolute normalized path');
+    }
+    const source = registryRoot === undefined
+        ? (0, pack_source_1.resolvePackSource)(packName)
+        : (0, pack_source_1.resolvePackSource)(packName, { registries: [{ name: 'manifest-provenance', remote: 'local', contentRoot: registryRoot }] });
+    const parsed = (0, contract_1.parseSensorPack)(JSON.parse(source.content), source.path);
+    if (parsed.kind !== 'v2')
+        throw new Error(`sensor pack "${packName}" does not provide a v2 compatibility contract`);
+    return resolveParsedPackCompatibility(cwd, parsed.pack, options);
+}
+/** Resolve a pre-parsed v2 pack. Init uses this when given an explicit registry root. */
+async function resolveParsedPackCompatibility(cwd, pack, options = {}) {
+    if (typeof cwd !== 'string' || cwd.trim() === '')
+        throw new Error('cwd must be a non-empty path');
+    if (!pack || typeof pack !== 'object' || pack.schemaVersion !== 2)
+        throw new Error('pack must be a parsed v2 sensor pack');
+    const evidence = (0, discovery_1.discoverProjectEvidence)(cwd, pack);
+    const executionPack = bindContainedRuntimeCommands(pack, evidence.pythonEnvironmentRoot);
+    const resolutionEvidence = { ...evidence, ...(options.packSelection === 'explicit' ? { packSelection: 'explicit' } : {}) };
+    const initial = (0, resolve_1.resolveProjectCompatibility)(executionPack, resolutionEvidence).sensors;
+    const sensors = {};
+    for (const [name, sensor] of Object.entries(executionPack.sensors)) {
+        const base = initial[name];
+        const variant = base.variantId === null ? null : sensor.variants.find(candidate => candidate.id === base.variantId) ?? null;
+        const probe = variant
+            ? await (0, probe_1.runCompatibilityProbe)(variant.probe, {
+                cwd,
+                toolExecutable: variant.command.executable,
+                toolResolution: variant.command.resolution,
+                pythonEnvironmentRoot: variant.command.pythonEnvironmentRoot,
+                configFiles: evidence.configFiles,
+                scripts: evidence.scripts,
+            })
+            : null;
+        sensors[name] = (0, resolve_1.resolveProjectCompatibility)({ ...executionPack, sensors: { [name]: sensor } }, { ...resolutionEvidence, probe: probe ?? undefined }).sensors[name];
+    }
+    return { pack: executionPack, sensors };
+}

package/dist/src/commands/sensors/compatibility/manifest.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.legacyCompatibility = legacyCompatibility;
+exports.parseSensorManifest = parseSensorManifest;
+exports.serializeManifestV2 = serializeManifestV2;
+const contract_1 = require("./contract");
+const semver_1 = __importDefault(require("semver"));
+const path_1 = __importDefault(require("path"));
+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 manifest${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 stringArray(value, source, location, allowEmpty) {
+    if (!Array.isArray(value) || (!allowEmpty && value.length === 0)) {
+        invalid(source, `${location} must be ${allowEmpty ? 'an array' : 'a nonempty array'}`);
+    }
+    return value.map((item, index) => text(item, source, `${location}[${index}]`));
+}
+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;
+}
+const STATES = new Set(['certified', 'compatible-unverified', 'incompatible', 'missing-tool', 'unverifiable', 'not-applicable']);
+function nullableText(value, source, location) {
+    return value === null ? null : text(value, source, location);
+}
+function parseCompatibilityEvidence(input, source, location) {
+    const value = record(input, source, location);
+    fields(value, ['state', 'reason', 'variantId', 'toolVersion', 'runtimeVersion', 'certifiedRange', 'evidence'], source, location);
+    if (typeof value.state !== 'string' || !STATES.has(value.state))
+        invalid(source, `${location}.state must be a supported state`);
+    if (!Array.isArray(value.evidence))
+        invalid(source, `${location}.evidence must be an array`);
+    const evidence = { state: value.state, reason: text(value.reason, source, `${location}.reason`), variantId: nullableText(value.variantId, source, `${location}.variantId`), toolVersion: nullableText(value.toolVersion, source, `${location}.toolVersion`), runtimeVersion: nullableText(value.runtimeVersion, source, `${location}.runtimeVersion`), certifiedRange: nullableText(value.certifiedRange, source, `${location}.certifiedRange`), evidence: value.evidence.map((entry, index) => { const item = record(entry, source, `${location}.evidence[${index}]`); fields(item, ['kind', 'status', 'path'], source, `${location}.evidence[${index}]`); return { kind: text(item.kind, source, `${location}.evidence[${index}].kind`), status: text(item.status, source, `${location}.evidence[${index}].status`), ...('path' in item ? { path: asset(item.path, source, `${location}.evidence[${index}].path`) } : {}) }; }) };
+    if (evidence.toolVersion !== null && semver_1.default.valid(evidence.toolVersion) === null)
+        invalid(source, `${location}.toolVersion must be a valid semver version`);
+    if (evidence.runtimeVersion !== null && semver_1.default.valid(evidence.runtimeVersion) === null)
+        invalid(source, `${location}.runtimeVersion must be a valid semver version`);
+    if (evidence.certifiedRange !== null && semver_1.default.validRange(evidence.certifiedRange) === null)
+        invalid(source, `${location}.certifiedRange must be a valid semver range`);
+    return evidence;
+}
+function legacyCompatibility(reason = 'legacy manifest without schemaVersion') {
+    if (typeof reason !== 'string' || reason.trim().length === 0 || /[\0\r\n]/.test(reason)) {
+        throw new Error('legacy compatibility reason must be a nonempty single-line string without NUL');
+    }
+    return {
+        state: 'compatible-unverified',
+        reason,
+        variantId: null,
+        toolVersion: null,
+        runtimeVersion: null,
+        certifiedRange: null,
+        evidence: [],
+    };
+}
+function parseLegacySensor(input, source, location) {
+    if (typeof input === 'string')
+        return { cmd: text(input, source, `${location}.cmd`) };
+    const value = record(input, source, location);
+    fields(value, ['cmd', 'fast', 'enabled', 'timeout', 'changedCmd', 'changedExtensions', 'formatter'], source, location);
+    const sensor = {};
+    if ('cmd' in value)
+        sensor.cmd = text(value.cmd, source, `${location}.cmd`);
+    if ('fast' in value) {
+        if (typeof value.fast !== 'boolean')
+            invalid(source, `${location}.fast must be a boolean`);
+        sensor.fast = value.fast;
+    }
+    if ('enabled' in value) {
+        if (typeof value.enabled !== 'boolean')
+            invalid(source, `${location}.enabled must be a boolean`);
+        sensor.enabled = value.enabled;
+    }
+    if ('timeout' in value) {
+        if (typeof value.timeout !== 'number' || !Number.isSafeInteger(value.timeout) || value.timeout <= 0)
+            invalid(source, `${location}.timeout must be a positive safe integer`);
+        sensor.timeout = value.timeout;
+    }
+    if ('changedCmd' in value)
+        sensor.changedCmd = text(value.changedCmd, source, `${location}.changedCmd`);
+    if ('changedExtensions' in value)
+        sensor.changedExtensions = stringArray(value.changedExtensions, source, `${location}.changedExtensions`, true);
+    if ('formatter' in value)
+        sensor.formatter = text(value.formatter, source, `${location}.formatter`);
+    return sensor;
+}
+function parseLegacyManifest(value, source) {
+    fields(value, ['pack', 'sensors', 'concurrency'], source, 'root');
+    const pack = id(value.pack, source, 'pack');
+    const sensorsInput = record(value.sensors, source, 'sensors');
+    const sensors = {};
+    for (const name of Object.keys(sensorsInput))
+        sensors[id(name, source, 'sensor id')] = parseLegacySensor(sensorsInput[name], source, `sensors.${name}`);
+    const manifest = { pack, sensors, compatibility: legacyCompatibility() };
+    if ('concurrency' in value) {
+        if (typeof value.concurrency !== 'number' || !Number.isSafeInteger(value.concurrency) || value.concurrency <= 0)
+            invalid(source, 'concurrency must be a positive safe integer');
+        manifest.concurrency = value.concurrency;
+    }
+    return manifest;
+}
+function parseV2Sensor(input, source, location) {
+    const value = record(input, source, location);
+    fields(value, ['enabled', 'fast', 'variantId', 'command', 'assets', 'policyRef', 'initializedCompatibility'], source, location);
+    if (typeof value.enabled !== 'boolean')
+        invalid(source, `${location}.enabled must be a boolean`);
+    const sensor = {
+        enabled: value.enabled, variantId: id(value.variantId, source, `${location}.variantId`),
+        command: (0, contract_1.parseStructuredCommand)(value.command, source),
+        initializedCompatibility: parseCompatibilityEvidence(value.initializedCompatibility, source, `${location}.initializedCompatibility`),
+    };
+    if (sensor.initializedCompatibility.variantId !== null && sensor.initializedCompatibility.variantId !== sensor.variantId)
+        invalid(source, `${location}.initializedCompatibility.variantId must match variantId`);
+    if (['certified', 'compatible-unverified', 'incompatible'].includes(sensor.initializedCompatibility.state) && sensor.initializedCompatibility.variantId === null)
+        invalid(source, `${location}.initializedCompatibility.variantId is required for ${sensor.initializedCompatibility.state}`);
+    if (sensor.initializedCompatibility.state === 'certified' && (sensor.initializedCompatibility.toolVersion === null || sensor.initializedCompatibility.runtimeVersion === null || sensor.initializedCompatibility.certifiedRange === null))
+        invalid(source, `${location}.initializedCompatibility certified evidence is incomplete`);
+    if (sensor.initializedCompatibility.state === 'certified' && !semver_1.default.satisfies(sensor.initializedCompatibility.toolVersion, sensor.initializedCompatibility.certifiedRange))
+        invalid(source, `${location}.initializedCompatibility.toolVersion must satisfy certifiedRange`);
+    if ('assets' in value)
+        sensor.assets = stringArray(value.assets, source, `${location}.assets`, true).map((entry, index) => asset(entry, source, `${location}.assets[${index}]`));
+    if ('policyRef' in value) {
+        if (value.policyRef !== 'shared/semgrep-policy.json')
+            invalid(source, `${location}.policyRef must be the contained AWM-owned shared/semgrep-policy.json`);
+        sensor.policyRef = value.policyRef;
+    }
+    if ('fast' in value) {
+        if (typeof value.fast !== 'boolean')
+            invalid(source, `${location}.fast must be a boolean`);
+        sensor.fast = value.fast;
+    }
+    return sensor;
+}
+function provenanceRoot(value, source) {
+    const parsed = text(value, source, 'registryRoot');
+    if (!path_1.default.isAbsolute(parsed) || path_1.default.normalize(parsed) !== parsed)
+        invalid(source, 'registryRoot must be an absolute normalized path');
+    return parsed;
+}
+function parseV2Manifest(value, source) {
+    fields(value, ['schemaVersion', 'pack', 'packSelection', 'registryRoot', 'sensors', 'concurrency'], source, 'root');
+    if (value.schemaVersion !== 2)
+        invalid(source, `unsupported manifest schemaVersion ${String(value.schemaVersion)}; supported: legacy, 2; upgrade or migrate the manifest`);
+    const pack = id(value.pack, source, 'pack');
+    const sensorsInput = record(value.sensors, source, 'sensors');
+    const sensors = {};
+    for (const name of Object.keys(sensorsInput))
+        sensors[id(name, source, 'sensor id')] = parseV2Sensor(sensorsInput[name], source, `sensors.${name}`);
+    const manifest = { schemaVersion: 2, pack, sensors };
+    if ('packSelection' in value) {
+        if (value.packSelection !== 'explicit')
+            invalid(source, 'packSelection must be "explicit" when present');
+        manifest.packSelection = 'explicit';
+    }
+    if ('registryRoot' in value)
+        manifest.registryRoot = provenanceRoot(value.registryRoot, source);
+    if ('concurrency' in value) {
+        if (typeof value.concurrency !== 'number' || !Number.isSafeInteger(value.concurrency) || value.concurrency <= 0)
+            invalid(source, 'concurrency must be a positive safe integer');
+        manifest.concurrency = value.concurrency;
+    }
+    return manifest;
+}
+function parseSensorManifest(input, source) {
+    const value = record(input, source, 'root');
+    return 'schemaVersion' in value ? { kind: 'v2', pack: parseV2Manifest(value, source) } : { kind: 'legacy', pack: parseLegacyManifest(value, source) };
+}
+function serializeManifestV2(input) {
+    const parsed = parseSensorManifest(input, 'manifest serialization');
+    if (parsed.kind !== 'v2')
+        throw new Error('Cannot serialize a legacy sensor manifest as v2');
+    return JSON.stringify(parsed.pack, null, 2);
+}

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

@@ -0,0 +1,134 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.materializeResolvedSensors = materializeResolvedSensors;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const manifest_1 = require("./manifest");
+const contract_1 = require("./contract");
+function stableId(value, label) {
+    if (typeof value !== 'string' || !/^[a-z][a-z0-9-]*$/.test(value))
+        throw new Error(`${label} must be a stable lowercase id`);
+    return value;
+}
+function containedAsset(value, label) {
+    if (typeof value !== 'string' || value.length === 0 || value.includes('\\') || path_1.default.isAbsolute(value) || value.split('/').some(part => !part || part === '.' || part === '..'))
+        throw new Error(`${label} must be a contained relative asset path`);
+    return value;
+}
+function root(value, label) {
+    if (typeof value !== 'string' || value.trim() === '')
+        throw new Error(`${label} must be a non-empty path`);
+    const resolved = path_1.default.resolve(value);
+    try {
+        if (!fs_1.default.statSync(resolved).isDirectory())
+            throw new Error();
+    }
+    catch {
+        throw new Error(`${label} must be an existing directory`);
+    }
+    return resolved;
+}
+function atomicWrite(destination, content) {
+    const directory = path_1.default.dirname(destination);
+    fs_1.default.mkdirSync(directory, { recursive: true });
+    const temporary = path_1.default.join(directory, `.${path_1.default.basename(destination)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        fs_1.default.writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx' });
+        fs_1.default.renameSync(temporary, destination);
+    }
+    finally {
+        try {
+            if (fs_1.default.existsSync(temporary))
+                fs_1.default.unlinkSync(temporary);
+        }
+        catch { /* best effort cleanup */ }
+    }
+}
+function priorAssets(projectRoot) {
+    const manifest = path_1.default.join(projectRoot, '.awm', 'sensors.json');
+    if (!fs_1.default.existsSync(manifest))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(fs_1.default.readFileSync(manifest, 'utf8'));
+    }
+    catch {
+        throw new Error(`cannot materialize over invalid sensor manifest ${manifest}`);
+    }
+    const parsedManifest = (0, manifest_1.parseSensorManifest)(parsed, manifest);
+    if (parsedManifest.kind !== 'v2')
+        return [];
+    return Object.values(parsedManifest.pack.sensors).flatMap(sensor => sensor.assets ?? []);
+}
+/** Write a selected, v2-only sensor configuration without overwriting user files.
+ * The manifest is the commit point: created assets are removed best-effort if writing it fails. */
+function materializeResolvedSensors(input) {
+    if (!input || typeof input !== 'object')
+        throw new Error('materialization input is required');
+    const projectRoot = root(input.projectRoot, 'projectRoot');
+    const packRoot = root(input.packRoot, 'packRoot');
+    const pack = stableId(input.pack, 'pack');
+    if (!input.sensors || typeof input.sensors !== 'object' || Array.isArray(input.sensors))
+        throw new Error('sensors must be an object');
+    const sensors = {};
+    for (const [name, sensor] of Object.entries(input.sensors)) {
+        stableId(name, 'sensor id');
+        // Reuse the durable parser as the single schema boundary before persisting.
+        const parsed = (0, manifest_1.parseSensorManifest)({ schemaVersion: 2, pack, sensors: { [name]: sensor } }, 'materialized sensor');
+        if (parsed.kind !== 'v2')
+            throw new Error('materialized sensor must be v2');
+        sensors[name] = parsed.pack.sensors[name];
+    }
+    const manifest = { schemaVersion: 2, pack, sensors, ...(input.packSelection === 'explicit' ? { packSelection: 'explicit' } : {}), ...(input.registryRoot ? { registryRoot: input.registryRoot } : {}) };
+    // A policy reference is deliberately not a materialized asset. Resolve it here
+    // from the registry-owned sibling only, so a manifest cannot turn arbitrary
+    // registry content into a project write through a cosmetic policy field.
+    for (const [name, sensor] of Object.entries(sensors)) {
+        if (sensor.policyRef)
+            (0, contract_1.resolveSemgrepPolicy)(sensor.policyRef, path_1.default.join(packRoot, 'pack.json'), `sensors.${name}`);
+    }
+    const selected = [...new Set(Object.values(sensors).flatMap(sensor => sensor.assets ?? []))].map((asset, index) => containedAsset(asset, `assets[${index}]`)).sort();
+    const prior = priorAssets(projectRoot);
+    const configured = [];
+    const preserved = [];
+    const created = [];
+    try {
+        if (input.configure !== false) {
+            for (const asset of selected) {
+                const source = path_1.default.join(packRoot, ...asset.split('/'));
+                const destination = path_1.default.join(projectRoot, ...asset.split('/'));
+                let stat;
+                try {
+                    stat = fs_1.default.lstatSync(source);
+                }
+                catch {
+                    throw new Error(`selected asset is missing from pack: ${asset}`);
+                }
+                if (!stat.isFile() || stat.isSymbolicLink())
+                    throw new Error(`selected asset must be a regular file: ${asset}`);
+                if (fs_1.default.existsSync(destination)) {
+                    preserved.push(asset);
+                    continue;
+                }
+                fs_1.default.mkdirSync(path_1.default.dirname(destination), { recursive: true });
+                atomicWrite(destination, fs_1.default.readFileSync(source, 'utf8'));
+                created.push(destination);
+                configured.push(asset);
+            }
+        }
+        atomicWrite(path_1.default.join(projectRoot, '.awm', 'sensors.json'), (0, manifest_1.serializeManifestV2)(manifest));
+    }
+    catch (error) {
+        for (const file of created.reverse()) {
+            try {
+                fs_1.default.unlinkSync(file);
+            }
+            catch { /* best effort transaction rollback */ }
+        }
+        throw error;
+    }
+    return { manifest, configured, preserved, orphaned: prior.filter(asset => !selected.includes(asset)).sort() };
+}

package/dist/src/commands/sensors/compatibility/pack-source.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePackSource = resolvePackSource;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const registries_1 = require("../../../core/registries");
+const MAX_PACK_BYTES = 1024 * 1024;
+function validPackName(pack) {
+    return typeof pack === 'string' && /^[a-z][a-z0-9-]*$/.test(pack);
+}
+function contained(root, candidate) {
+    const prefix = root.endsWith(path_1.default.sep) ? root : root + path_1.default.sep;
+    return candidate.startsWith(prefix);
+}
+/** Walk each component under contentRoot with lstat: realpath alone would hide an
+ * internal symlink whose target happens to remain inside the registry. */
+function inspectContainedPack(root, pack) {
+    const components = ['sensor-packs', pack, 'pack.json'];
+    let candidate = root;
+    for (let index = 0; index < components.length; index++) {
+        candidate = path_1.default.join(candidate, components[index]);
+        let stat;
+        try {
+            stat = fs_1.default.lstatSync(candidate);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            if (error.code === 'ENOTDIR')
+                throw new Error(`pack source ${candidate} has a non-regular or symbolic parent`);
+            throw new Error(`cannot inspect pack source ${candidate}`);
+        }
+        if (stat.isSymbolicLink())
+            throw new Error(`pack source ${candidate} must not contain symbolic links`);
+        if (index < components.length - 1 && !stat.isDirectory())
+            throw new Error(`pack source ${candidate} has a non-regular parent`);
+        if (index === components.length - 1)
+            return { candidate, stat };
+    }
+    throw new Error('pack source component walk did not reach pack.json');
+}
+/** Resolve only an exact, regular pack.json beneath the first configured registry.
+ * Registry order is authority; an unsafe claimed source is a hard failure, not a fallback. */
+function resolvePackSource(pack, options = {}) {
+    if (!validPackName(pack))
+        throw new Error('pack name must be a stable lowercase id');
+    const registries = options.registries ?? (0, registries_1.listRegistries)();
+    if (!Array.isArray(registries))
+        throw new Error('registries must be an array');
+    for (const registry of registries) {
+        if (!registry || typeof registry.contentRoot !== 'string' || registry.contentRoot.trim() === '')
+            throw new Error('registry has an invalid content root');
+        const inspected = inspectContainedPack(registry.contentRoot, pack);
+        if (!inspected)
+            continue;
+        const { candidate, stat } = inspected;
+        if (!stat.isFile())
+            throw new Error(`pack source ${candidate} must be a contained regular file, never a symbolic link`);
+        if (stat.size > MAX_PACK_BYTES)
+            throw new Error(`pack source ${candidate} exceeds the 1 MiB limit`);
+        let root;
+        let real;
+        try {
+            root = fs_1.default.realpathSync(registry.contentRoot);
+            real = fs_1.default.realpathSync(candidate);
+        }
+        catch {
+            throw new Error(`cannot canonicalize pack source ${candidate}`);
+        }
+        if (!contained(root, real))
+            throw new Error(`pack source ${candidate} escapes its registry root`);
+        return { path: real, content: fs_1.default.readFileSync(real, 'utf8'), registry };
+    }
+    throw new Error(`sensor pack "${pack}" was not found in configured registries`);
+}

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCompatibilityProbe = runCompatibilityProbe;
+const exec_1 = require("../exec");
+const KINDS = new Set(['version', 'eslint-print-config', 'typescript-show-config', 'semgrep-validate', 'package-script-present', 'config-present']);
+function commandFor(kind, evidence) {
+    const executable = evidence.toolExecutable ?? (kind.startsWith('typescript') ? 'tsc' : kind.startsWith('eslint') ? 'eslint' : kind.startsWith('semgrep') ? 'semgrep' : 'node');
+    // Probe an executable through the same bounded resolver as its variant's
+    // eventual execution. Falling back preserves legacy probe-only kinds.
+    const resolution = executable === 'node'
+        ? 'path'
+        : evidence.toolResolution ?? (kind === 'semgrep-validate'
+            ? 'python-environment'
+            : 'node-modules-bin');
+    if (kind === 'package-script-present')
+        return null;
+    if (kind === 'config-present')
+        return null;
+    const command = { executable, resolution, ...(resolution === 'python-environment' && evidence.pythonEnvironmentRoot ? { pythonEnvironmentRoot: evidence.pythonEnvironmentRoot } : {}) };
+    if (kind === 'version')
+        return { ...command, args: ['--version'] };
+    if (kind === 'eslint-print-config')
+        return { ...command, args: ['--print-config', evidence.configFiles?.[0] ?? 'package.json'] };
+    if (kind === 'typescript-show-config')
+        return { ...command, args: ['--showConfig'] };
+    return { ...command, args: ['--validate'] };
+}
+/** Executes only the closed probe enum. Raw output is intentionally discarded. */
+async function runCompatibilityProbe(probe, evidence, executor = exec_1.runStructuredCommand) {
+    if (!probe || typeof probe !== 'object' || !KINDS.has(probe.kind))
+        throw new Error('compatibility probe kind must be allowed');
+    if (!evidence || typeof evidence.cwd !== 'string' || evidence.cwd.trim() === '')
+        throw new Error('probe evidence requires cwd');
+    if (probe.kind === 'package-script-present')
+        return { status: (evidence.scripts?.length ?? 0) > 0 ? 'matched' : 'not-matched', reason: 'package-script' };
+    if (probe.kind === 'config-present')
+        return { status: (evidence.configFiles?.length ?? 0) > 0 ? 'matched' : 'not-matched', reason: 'config-file' };
+    try {
+        const result = await executor(commandFor(probe.kind, evidence), { cwd: evidence.cwd, timeout: 5_000, maxBuffer: 64 * 1024 });
+        if (result.timedOut || result.overflowed || result.spawnError)
+            return { status: 'unverifiable', reason: result.timedOut ? 'probe-timeout' : result.overflowed ? 'probe-output-limit' : 'probe-spawn-error' };
+        return result.code === 0 ? { status: 'matched', reason: 'probe-exit-zero' } : { status: 'not-matched', reason: 'probe-exit-nonzero' };
+    }
+    catch {
+        return { status: 'unverifiable', reason: 'probe-exception' };
+    }
+}