agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/registries/packageRegistry.js

@@ -3,14 +3,14 @@ import path from "node:path";
 import { loadYamlMapping } from "../core/yaml.js";
 import { resolvePath } from "../core/paths.js";
 import { resolveSourceRoot } from "../core/sourceRoot.js";
+/** PackageManifest registry loader and contract validator. Port of scripts/package_registry.py. */
 export const EXPECTED_PACKAGE_ORDER = ["agentera"];
 export const REQUIRED_GROUPS = [
     "identity",
     "version_authority",
     "version_surfaces",
-    "runtime_package_manifests",
     "bundle_surfaces",
-    "package_commands",
+    "bootstrap_command_authority",
     "docs_targets",
     "release_policy",
 ];
@@ -22,11 +22,10 @@ const REQUIRED_FIELDS = {
         "access_interface",
         "future_authority_change_requires",
     ],
-    version_surfaces: ["surfaces", "excluded_runtime_manifests"],
-    runtime_package_manifests: ["manifests", "shared_paths", "shared_paths_policy"],
-    bundle_surfaces: ["directories", "files", "skip_parts", "skip_suffixes"],
-    package_commands: ["commands", "safety"],
-    docs_targets: ["version_files_source", "version_files", "index_targets", "excluded_version_files"],
+    version_surfaces: ["surfaces"],
+    bundle_surfaces: ["directories", "files", "generated_files", "skip_parts", "skip_suffixes"],
+    bootstrap_command_authority: ["scanned_formats", "scalar_classifications", "emitted_producers", "constructor_non_producers"],
+    docs_targets: ["version_files_source", "version_files", "index_targets"],
     release_policy: [
         "semver_policy_source",
         "version_bump_required_for_interface_only_change",
@@ -34,17 +33,11 @@ const REQUIRED_FIELDS = {
     ],
 };
 const CONSUMER_GROUPS = {
-    validator: ["identity", "version_authority", "version_surfaces", "runtime_package_manifests"],
-    upgrade: ["identity", "version_authority", "bundle_surfaces", "package_commands"],
+    validator: ["identity", "version_authority", "version_surfaces"],
+    upgrade: ["identity", "version_authority", "bundle_surfaces", "bootstrap_command_authority"],
     docs: ["identity", "version_authority", "docs_targets", "release_policy"],
     tests: REQUIRED_GROUPS,
 };
-const APPROVED_EXECUTABLES = new Set(["npx"]);
-const APPROVED_ACTIONS = new Set(["remove-legacy-skills", "install-agentera-skill"]);
-const APPROVED_RUNTIMES = new Set(["all", "claude", "opencode"]);
-const APPROVED_RUNTIME_AGENTS = new Set(["claude-code", "opencode"]);
-const CLEANUP_ACTIONS = new Set(["remove-legacy-skills"]);
-const RUNTIME_INSTALL_ACTIONS = new Set(["install-agentera-skill"]);
 const FORBIDDEN_INSTALL_ROOT_FIELDS = new Set([
     "install_root",
     "install_root_classification",
@@ -80,6 +73,29 @@ function isMapping(value) {
 function isStringList(value) {
     return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function selectorParts(selector) {
+    const parts = [];
+    for (const match of selector.matchAll(/([^[.\]]+)|\[(\d+)\]/g)) {
+        parts.push(match[2] === undefined ? match[1] : Number(match[2]));
+    }
+    return parts;
+}
+function selectedVersion(root, surface) {
+    const source = fs.readFileSync(path.join(root, surface.path), "utf8");
+    if (surface.selector === "frontmatter.version") {
+        return /^version:\s*["']?([^"'\s]+)["']?\s*$/m.exec(source)?.[1] ?? null;
+    }
+    let value = JSON.parse(source);
+    for (const part of selectorParts(surface.selector)) {
+        if (typeof part === "number") {
+            value = Array.isArray(value) ? value[part] : undefined;
+        }
+        else {
+            value = isMapping(value) ? value[part] : undefined;
+        }
+    }
+    return typeof value === "string" ? value : null;
+}
 export class PackageRegistry {
     records;
     root;
@@ -105,11 +121,11 @@ export class PackageRegistry {
             authority.selector !== "skills[0].version") {
             throw new RegistryError("unsupported suite version authority selector");
         }
-        let data;
+        let data; // cast: JSON.parse IO boundary
         try {
             data = JSON.parse(fs.readFileSync(path.join(this.root, authority.persisted_authority), "utf8"));
         }
-        catch (exc) {
+        catch {
             throw new RegistryError(`registry.json missing skills[0].version`);
         }
         const version = data?.skills?.[0]?.version;
@@ -137,34 +153,12 @@ export class PackageRegistry {
     versionSurfaceIds(packageId = "agentera") {
         return this.get(packageId).version_surfaces.surfaces.map((s) => s.id);
     }
-    runtimeManifestIds(packageId = "agentera") {
-        return this.get(packageId).runtime_package_manifests.manifests.map((m) => m.id);
-    }
-    runtimeManifestPaths(packageId = "agentera") {
-        const paths = {};
-        for (const manifest of this.get(packageId).runtime_package_manifests.manifests) {
-            if (!(manifest.runtime in paths)) {
-                paths[manifest.runtime] = manifest.path;
-            }
-        }
-        return paths;
-    }
-    runtimePackageShapes(packageId = "agentera") {
-        const shapes = {};
-        for (const manifest of this.get(packageId).runtime_package_manifests.manifests) {
-            shapes[manifest.runtime] = manifest.package_shape;
-        }
-        return shapes;
-    }
-    sharedPathRequirements(packageId = "agentera") {
-        const requirements = {};
-        for (const entry of this.get(packageId).runtime_package_manifests.shared_paths) {
-            requirements[entry.path] = entry.kind;
+    versionSurfaceValues(packageId = "agentera") {
+        const values = {};
+        for (const surface of this.get(packageId).version_surfaces.surfaces) {
+            values[surface.id] = selectedVersion(this.root, surface);
         }
-        return requirements;
-    }
-    nonVersionBearingRuntimeManifests(packageId = "agentera") {
-        return this.get(packageId).runtime_package_manifests.manifests.filter((m) => m.version_bearing === false);
+        return values;
     }
 }
 export function loadRegistry(registryPath = defaultRegistryPath(), root = defaultRoot()) {
@@ -173,7 +167,7 @@ export function loadRegistry(registryPath = defaultRegistryPath(), root = defaul
     if (errors.length > 0) {
         throw new RegistryError("PackageManifest registry validation failed: " + errors.join("; "));
     }
-    return new PackageRegistry(data.records, root);
+    return new PackageRegistry(data.records, root); // cast: parsed registry IO boundary
 }
 export function validateRegistryFile(registryPath = defaultRegistryPath(), root = defaultRoot()) {
     return validateRegistryData(loadYamlMapping(fs.readFileSync(registryPath, "utf8")), root);
@@ -263,14 +257,11 @@ function validateGroup(prefix, group, value, root) {
         case "version_surfaces":
             errors.push(...validateVersionSurfaces(prefix, value, root));
             break;
-        case "runtime_package_manifests":
-            errors.push(...validateRuntimeManifests(prefix, value, root));
-            break;
         case "bundle_surfaces":
-            errors.push(...validateBundleSurfaces(prefix, value, root));
+            errors.push(...validateBundleSurfaces(prefix, value));
             break;
-        case "package_commands":
-            errors.push(...validatePackageCommands(prefix, value));
+        case "bootstrap_command_authority":
+            errors.push(...validateBootstrapCommandAuthority(prefix, value, root));
             break;
         case "docs_targets":
             errors.push(...validateDocsTargets(prefix, value, root));
@@ -325,141 +316,196 @@ function validateVersionSurfaces(prefix, value, root) {
             errors.push(...validateRepoPath(`${surfacePrefix}.path`, surface.path, root));
         });
     }
-    errors.push(...validatePathList(`${prefix}.excluded_runtime_manifests`, value.excluded_runtime_manifests, root));
     return errors;
 }
-function validateRuntimeManifests(prefix, value, root) {
+function validateBundleSurfaces(prefix, value) {
     const errors = [];
-    const manifests = value.manifests;
-    if (!Array.isArray(manifests)) {
-        errors.push(`${prefix}.manifests must be a list`);
-    }
-    else {
-        errors.push(...validateIdList(`${prefix}.manifests`, manifests));
-        let nonVersionBearing = 0;
-        manifests.forEach((manifest, index) => {
-            const manifestPrefix = `${prefix}.manifests[${index}]`;
-            if (!isMapping(manifest)) {
-                errors.push(`${manifestPrefix} must be an object`);
+    const ids = new Map();
+    const paths = new Map();
+    for (const field of ["directories", "files"]) {
+        const entries = value[field];
+        if (!Array.isArray(entries)) {
+            errors.push(`${prefix}.${field} must be a list`);
+            continue;
+        }
+        entries.forEach((entry, index) => {
+            const entryPrefix = `${prefix}.${field}[${index}]`;
+            if (!isMapping(entry)) {
+                errors.push(`${entryPrefix} must be an object`);
                 return;
             }
-            errors.push(...validateRequiredObjectFields(manifestPrefix, manifest, [
-                "id",
-                "runtime",
-                "path",
-                "version_bearing",
-                "package_shape",
-            ]));
-            errors.push(...validateRepoPath(`${manifestPrefix}.path`, manifest.path, root));
-            if (typeof manifest.version_bearing !== "boolean") {
-                errors.push(`${manifestPrefix}.version_bearing must be a boolean`);
+            errors.push(...validateRequiredObjectFields(entryPrefix, entry, ["id", "path"]));
+            const entryId = entry.id;
+            if (typeof entryId === "string" && entryId.length > 0) {
+                const previous = ids.get(entryId);
+                if (previous !== undefined) {
+                    errors.push(`${entryPrefix}.id ${JSON.stringify(entryId)} duplicates ${previous}.id; ` +
+                        "correction: use a unique id across bundle directories and files");
+                }
+                else {
+                    ids.set(entryId, entryPrefix);
+                }
             }
-            else if (manifest.version_bearing === false) {
-                nonVersionBearing += 1;
+            const entryPath = entry.path;
+            errors.push(...validateBundlePath(entryPrefix, entryId, entryPath));
+            if (typeof entryPath === "string" && entryPath.length > 0) {
+                const previous = paths.get(entryPath);
+                if (previous !== undefined) {
+                    errors.push(`${entryPrefix}.path ${JSON.stringify(entryPath)} for id ${JSON.stringify(entryId)} ` +
+                        `duplicates ${previous}.path; correction: use a unique path across bundle directories and files`);
+                }
+                else {
+                    paths.set(entryPath, entryPrefix);
+                }
             }
         });
-        if (nonVersionBearing === 0) {
-            errors.push(`${prefix}.manifests must include non-version-bearing runtime package manifests separately`);
+    }
+    for (const field of ["skip_parts", "skip_suffixes"]) {
+        if (!isStringList(value[field])) {
+            errors.push(`${prefix}.${field} must be a list of strings`);
         }
     }
-    const sharedPaths = value.shared_paths;
-    if (!Array.isArray(sharedPaths)) {
-        errors.push(`${prefix}.shared_paths must be a list`);
+    const generated = value.generated_files;
+    if (!Array.isArray(generated)) {
+        errors.push(`${prefix}.generated_files must be a list`);
     }
     else {
-        errors.push(...validateIdList(`${prefix}.shared_paths`, sharedPaths));
-        sharedPaths.forEach((entry, index) => {
-            const entryPrefix = `${prefix}.shared_paths[${index}]`;
+        generated.forEach((entry, index) => {
+            const entryPrefix = `${prefix}.generated_files[${index}]`;
             if (!isMapping(entry)) {
                 errors.push(`${entryPrefix} must be an object`);
                 return;
             }
-            errors.push(...validateRequiredObjectFields(entryPrefix, entry, ["id", "path", "kind"]));
-            errors.push(...validateRepoPath(`${entryPrefix}.path`, entry.path, root));
-            if (entry.kind !== "dir" && entry.kind !== "file") {
-                errors.push(`${entryPrefix}.kind must be dir or file`);
+            errors.push(...validateRequiredObjectFields(entryPrefix, entry, ["id", "path", "format", "classification", "command_authority_reason"]));
+            errors.push(...validateBundlePath(entryPrefix, entry.id, entry.path));
+            if (typeof entry.id === "string" && entry.id) {
+                const previous = ids.get(entry.id);
+                if (previous)
+                    errors.push(`${entryPrefix}.id ${JSON.stringify(entry.id)} duplicates ${previous}.id; correction: use a unique id across all bundle surfaces`);
+                else
+                    ids.set(entry.id, entryPrefix);
+            }
+            if (typeof entry.path === "string" && entry.path) {
+                const previous = paths.get(entry.path);
+                if (previous)
+                    errors.push(`${entryPrefix}.path ${JSON.stringify(entry.path)} for id ${JSON.stringify(entry.id)} duplicates ${previous}.path; correction: use a unique path across all bundle surfaces`);
+                else
+                    paths.set(entry.path, entryPrefix);
+            }
+            if (entry.format !== "json")
+                errors.push(`${entryPrefix}.format must be json`);
+            if (entry.classification !== "active")
+                errors.push(`${entryPrefix}.classification must be active`);
+            if (typeof entry.command_authority_reason !== "string" || !entry.command_authority_reason) {
+                errors.push(`${entryPrefix}.command_authority_reason must be a non-empty string`);
             }
         });
     }
-    if (typeof value.shared_paths_policy !== "string" || !value.shared_paths_policy) {
-        errors.push(`${prefix}.shared_paths_policy must be a non-empty string`);
-    }
     return errors;
 }
-function validateBundleSurfaces(prefix, value, root) {
+function validateBootstrapCommandAuthority(prefix, value, root) {
     const errors = [];
-    for (const field of ["directories", "files"]) {
+    const formats = value.scanned_formats;
+    if (!Array.isArray(formats) || !formats.every((item) => typeof item === "string") || new Set(formats).size !== 3 || !["markdown", "yaml", "json"].every((format) => formats.includes(format))) {
+        errors.push(`${prefix}.scanned_formats must contain exactly markdown, yaml, and json`);
+    }
+    for (const field of ["emitted_producers", "constructor_non_producers"]) {
         const entries = value[field];
         if (!Array.isArray(entries)) {
             errors.push(`${prefix}.${field} must be a list`);
             continue;
         }
-        errors.push(...validateIdList(`${prefix}.${field}`, entries));
+        const paths = new Set();
         entries.forEach((entry, index) => {
             const entryPrefix = `${prefix}.${field}[${index}]`;
             if (!isMapping(entry)) {
                 errors.push(`${entryPrefix} must be an object`);
                 return;
             }
-            errors.push(...validateRequiredObjectFields(entryPrefix, entry, ["id", "path"]));
+            errors.push(...validateRequiredObjectFields(entryPrefix, entry, ["path", "reason"]));
             errors.push(...validateRepoPath(`${entryPrefix}.path`, entry.path, root));
+            if (typeof entry.reason !== "string" || !entry.reason)
+                errors.push(`${entryPrefix}.reason must be a non-empty string`);
+            if (typeof entry.path === "string") {
+                if (paths.has(entry.path))
+                    errors.push(`${entryPrefix}.path duplicates ${JSON.stringify(entry.path)}`);
+                paths.add(entry.path);
+            }
         });
     }
-    for (const field of ["skip_parts", "skip_suffixes"]) {
-        if (!isStringList(value[field])) {
-            errors.push(`${prefix}.${field} must be a list of strings`);
-        }
-    }
-    return errors;
-}
-function validatePackageCommands(prefix, value) {
-    const errors = [];
-    const commands = value.commands;
-    if (!Array.isArray(commands)) {
-        errors.push(`${prefix}.commands must be a list`);
+    const classifications = value.scalar_classifications;
+    if (!Array.isArray(classifications)) {
+        errors.push(`${prefix}.scalar_classifications must be a list`);
     }
     else {
-        errors.push(...validateIdList(`${prefix}.commands`, commands));
-        commands.forEach((command, index) => {
-            const commandPrefix = `${prefix}.commands[${index}]`;
-            if (!isMapping(command)) {
-                errors.push(`${commandPrefix} must be an object`);
+        const identities = new Set();
+        const reasons = new Set();
+        classifications.forEach((entry, index) => {
+            const entryPrefix = `${prefix}.scalar_classifications[${index}]`;
+            if (!isMapping(entry)) {
+                errors.push(`${entryPrefix} must be an object`);
                 return;
             }
-            errors.push(...validateRequiredObjectFields(commandPrefix, command, [
-                "id",
-                "runtime",
-                "action",
-                "phase",
-                "argv",
-                "skipped_without_update_packages_message",
+            errors.push(...validateRequiredObjectFields(entryPrefix, entry, [
+                "path",
+                "region",
+                "category",
+                "classification",
+                "normalized_sha256",
+                "reason",
             ]));
-            errors.push(...validateCommandSpec(commandPrefix, command));
+            errors.push(...validateRepoPath(`${entryPrefix}.path`, entry.path, root));
+            if (typeof entry.region !== "string" || !entry.region)
+                errors.push(`${entryPrefix}.region must be a non-empty string`);
+            if (!["identity_only", "argument_bearing", "other_vocabulary"].includes(String(entry.category)))
+                errors.push(`${entryPrefix}.category is invalid`);
+            if (!["bounded_descriptive", "exact_exemption"].includes(String(entry.classification)))
+                errors.push(`${entryPrefix}.classification is invalid`);
+            if (typeof entry.normalized_sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(entry.normalized_sha256))
+                errors.push(`${entryPrefix}.normalized_sha256 must be lowercase SHA-256`);
+            if (typeof entry.reason !== "string" || !entry.reason)
+                errors.push(`${entryPrefix}.reason must be a non-empty string`);
+            else if (reasons.has(entry.reason))
+                errors.push(`${entryPrefix}.reason duplicates another scalar-specific reason`);
+            else
+                reasons.add(entry.reason);
+            if (typeof entry.path === "string" && typeof entry.region === "string") {
+                const identity = `${entry.path}\u0000${entry.region}`;
+                if (identities.has(identity))
+                    errors.push(`${entryPrefix} duplicates path and region ${JSON.stringify(entry.path)} ${JSON.stringify(entry.region)}`);
+                identities.add(identity);
+            }
         });
     }
-    const safety = value.safety;
-    const expectedSafety = {
-        argv_only: true,
-        update_packages_required_to_plan: true,
-        yes_required_to_execute: true,
-        preserve_existing_write_gates: true,
-        cleanup_phase: "cleanup",
-        runtime_install_phase: "runtime-install",
-    };
-    if (!isMapping(safety)) {
-        errors.push(`${prefix}.safety must be an object`);
-    }
-    else if (!shallowEqual(safety, expectedSafety)) {
-        errors.push(`${prefix}.safety must preserve approved write gates and phase names`);
-    }
     return errors;
 }
+function validateBundlePath(prefix, id, value) {
+    const segments = typeof value === "string" ? value.split("/") : [];
+    const invalid = typeof value !== "string" ||
+        value.length === 0 ||
+        path.posix.isAbsolute(value) ||
+        path.win32.isAbsolute(value) ||
+        /^[A-Za-z]:/.test(value) ||
+        value.includes("\\") ||
+        value.startsWith("./") ||
+        value.endsWith("/") ||
+        segments.includes(".") ||
+        segments.includes("..") ||
+        path.posix.normalize(value) !== value;
+    if (!invalid)
+        return [];
+    return [
+        `${prefix}.path ${JSON.stringify(value)} for id ${JSON.stringify(id)} is invalid; ` +
+            "correction: use a non-empty normalized relative POSIX path without absolute roots, " +
+            "drive prefixes, backslashes, leading './', trailing separators, or '.'/'..' segments",
+    ];
+}
 function validateDocsTargets(prefix, value, root) {
     const errors = [];
     if (typeof value.version_files_source !== "string" || !value.version_files_source) {
         errors.push(`${prefix}.version_files_source must be a non-empty string`);
     }
-    for (const field of ["version_files", "index_targets", "excluded_version_files"]) {
+    for (const field of ["version_files", "index_targets"]) {
         errors.push(...validatePathList(`${prefix}.${field}`, value[field], root));
     }
     return errors;
@@ -479,51 +525,6 @@ function validateReleasePolicy(prefix, value) {
     }
     return errors;
 }
-function validateCommandSpec(prefix, command) {
-    const errors = [];
-    const runtime = command.runtime;
-    const action = command.action;
-    const phase = command.phase;
-    const argv = command.argv;
-    if (!APPROVED_RUNTIMES.has(runtime)) {
-        errors.push(`${prefix}.runtime ${pyRepr(runtime)} is not approved`);
-    }
-    if (!APPROVED_ACTIONS.has(action)) {
-        errors.push(`${prefix}.action ${pyRepr(action)} is not approved`);
-    }
-    if (!Array.isArray(argv) || argv.length === 0 || !argv.every((part) => typeof part === "string")) {
-        errors.push(`${prefix}.argv must be a list of strings`);
-        return errors;
-    }
-    if (!APPROVED_EXECUTABLES.has(argv[0])) {
-        errors.push(`${prefix}.argv uses unapproved executable ${pyRepr(argv[0])}`);
-    }
-    if (argv.length < 3 || argv[1] !== "skills" || !["remove", "add"].includes(argv[2])) {
-        errors.push(`${prefix}.argv must use approved skills action`);
-    }
-    if (CLEANUP_ACTIONS.has(action) && (runtime !== "all" || phase !== "cleanup" || argv[2] !== "remove")) {
-        errors.push(`${prefix}: cleanup commands must stay separate from runtime installs`);
-    }
-    if (RUNTIME_INSTALL_ACTIONS.has(action)) {
-        if (runtime === "all" || phase !== "runtime-install" || argv[2] !== "add") {
-            errors.push(`${prefix}: runtime install commands must stay out of cleanup`);
-        }
-        if (!argv.includes("-a")) {
-            errors.push(`${prefix}: runtime install commands must declare runtime agent`);
-        }
-        else {
-            const agentIndex = argv.indexOf("-a") + 1;
-            const agent = agentIndex < argv.length ? argv[agentIndex] : null;
-            if (agent === null || !APPROVED_RUNTIME_AGENTS.has(agent)) {
-                errors.push(`${prefix}: runtime install agent ${pyRepr(agent)} is not approved`);
-            }
-        }
-    }
-    if (typeof command.skipped_without_update_packages_message !== "string") {
-        errors.push(`${prefix}.skipped_without_update_packages_message must be a string`);
-    }
-    return errors;
-}
 function validateRequiredObjectFields(prefix, value, expected) {
     const errors = [];
     for (const field of expected) {
@@ -536,7 +537,7 @@ function validateRequiredObjectFields(prefix, value, expected) {
             errors.push(`${prefix}: unknown field ${field}`);
         }
     }
-    for (const field of ["id", "runtime", "action", "phase", "selector", "package_shape"]) {
+    for (const field of ["id", "selector"]) {
         if (field in value && (typeof value[field] !== "string" || !value[field])) {
             errors.push(`${prefix}.${field} must be a non-empty string`);
         }
@@ -585,11 +586,10 @@ function validateRepoPath(prefix, value, root) {
     if (rel !== "" && (rel.startsWith("..") || path.isAbsolute(rel))) {
         return [`${prefix} must stay inside repo root`];
     }
-    // Existence is advisory for a package DISTRIBUTION spec: surfaces such as
-    // version files, plugin manifests, and build outputs may be generated at
-    // build/release time or be runtime-specific, and need not be present in every
-    // checkout (e.g. a node-only tree without the Python build files). Structural
-    // and traversal safety above still apply.
+    // Existence is advisory for a package distribution spec: version files and
+    // build outputs may be generated at build/release time and need not be
+    // present in every checkout. Structural and traversal safety above still
+    // apply.
     return [];
 }
 function validateForbiddenFields(prefix, value) {
@@ -615,27 +615,3 @@ function validateForbiddenFields(prefix, value) {
     }
     return errors;
 }
-function shallowEqual(a, b) {
-    const ak = Object.keys(a);
-    const bk = Object.keys(b);
-    if (ak.length !== bk.length) {
-        return false;
-    }
-    for (const k of ak) {
-        if (a[k] !== b[k]) {
-            return false;
-        }
-    }
-    return true;
-}
-/** Mirror Python repr() for the scalar values used in validator messages. */
-function pyRepr(value) {
-    if (value === null || value === undefined) {
-        return "None";
-    }
-    if (typeof value === "string") {
-        return `'${value}'`;
-    }
-    return String(value);
-}
-//# sourceMappingURL=packageRegistry.js.map