agentic-workflow-manager 6.5.2 → 8.0.0

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 } : {}) }, 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(),
+    };
+}

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

@@ -0,0 +1,59 @@
+"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"));
+/**
+ * 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) {
+    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);
+}
+/** Resolve a pre-parsed v2 pack. Init uses this when given an explicit registry root. */
+async function resolveParsedPackCompatibility(cwd, pack) {
+    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 initial = (0, resolve_1.resolveProjectCompatibility)(pack, evidence).sensors;
+    const sensors = {};
+    for (const [name, sensor] of Object.entries(pack.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,
+                configFiles: evidence.configFiles,
+                scripts: evidence.scripts,
+            })
+            : null;
+        sensors[name] = (0, resolve_1.resolveProjectCompatibility)({ ...pack, sensors: { [name]: sensor } }, { ...evidence, probe: probe ?? undefined }).sensors[name];
+    }
+    return { pack, sensors };
+}

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

@@ -0,0 +1,197 @@
+"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', '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`, false).map((entry, index) => asset(entry, source, `${location}.assets[${index}]`));
+    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', '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 ('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,126 @@
+"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");
+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.registryRoot ? { registryRoot: input.registryRoot } : {}) };
+    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`);
+}