agentera 3.0.0-dev.5 → 3.0.0-dev.6

package/dist/migrate/v2HandoffManifest.js

@@ -0,0 +1,333 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isFile, pathExists, resolvePath } from "../core/paths.js";
+import { doctorRoots, loadSuiteVersion } from "../upgrade/appModel.js";
+import { AGENTERA_USER_STATE_NAMES, ROOT_USER_STATE_DIR_NAMES, ROOT_USER_STATE_FILE_NAMES, } from "../upgrade/doctor.js";
+/** Contract authority: references/cli/v3-handoff-manifest.schema.yaml */
+export const V2_HANDOFF_MANIFEST_SCHEMA_REL = "references/cli/v3-handoff-manifest.schema.yaml";
+export const V2_HANDOFF_MANIFEST_FILENAME = "v3-handoff.json";
+export const V2_HANDOFF_SCHEMA_VERSION = "agentera.v3_handoff_manifest.v1";
+export const READER_PREFLIGHT_BUDGET_MS = 100;
+export const USER_DATA_CATALOG_DIRS = [
+    "benchmarks",
+    "intermediate",
+    "sessions",
+    "history",
+    "corpus",
+];
+export const PROFILE_FILE_MEMBERS = ["PROFILE.md", "USAGE.md"];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asNonEmptyString(value, field) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function parseDirectoryEntry(raw) {
+    const id = asNonEmptyString(raw.id, "user_data_inventory.id");
+    if (!USER_DATA_CATALOG_DIRS.includes(id)) {
+        throw new Error(`user_data_inventory id ${id} is not in the catalog`);
+    }
+    if (raw.kind !== "directory") {
+        throw new Error(`user_data_inventory entry ${id} must have kind=directory`);
+    }
+    if (typeof raw.exists !== "boolean") {
+        throw new Error(`user_data_inventory entry ${id} must have boolean exists`);
+    }
+    return {
+        id: id,
+        relative_path: asNonEmptyString(raw.relative_path, `user_data_inventory.${id}.relative_path`),
+        kind: "directory",
+        exists: raw.exists,
+    };
+}
+function parseProfileFilesEntry(raw) {
+    if (raw.id !== "profile_files") {
+        throw new Error("profile_files entry must have id=profile_files");
+    }
+    if (raw.kind !== "profile_files") {
+        throw new Error("profile_files entry must have kind=profile_files");
+    }
+    if (!Array.isArray(raw.members)) {
+        throw new Error("profile_files entry must have members array");
+    }
+    const members = raw.members.map((member, index) => {
+        if (!isRecord(member)) {
+            throw new Error(`profile_files.members[${index}] must be an object`);
+        }
+        if (member.kind !== "file") {
+            throw new Error(`profile_files.members[${index}] must have kind=file`);
+        }
+        if (typeof member.exists !== "boolean") {
+            throw new Error(`profile_files.members[${index}] must have boolean exists`);
+        }
+        return {
+            relative_path: asNonEmptyString(member.relative_path, `profile_files.members[${index}].relative_path`),
+            kind: "file",
+            exists: member.exists,
+        };
+    });
+    return { id: "profile_files", kind: "profile_files", members };
+}
+function parseUserDataInventory(raw) {
+    if (!Array.isArray(raw) || raw.length < 6) {
+        throw new Error("user_data_inventory must be an array with at least six entries");
+    }
+    const entries = raw.map((item, index) => {
+        if (!isRecord(item)) {
+            throw new Error(`user_data_inventory[${index}] must be an object`);
+        }
+        if (item.kind === "profile_files") {
+            return parseProfileFilesEntry(item);
+        }
+        return parseDirectoryEntry(item);
+    });
+    const ids = new Set(entries.map((entry) => entry.id));
+    for (const id of [...USER_DATA_CATALOG_DIRS, "profile_files"]) {
+        if (!ids.has(id)) {
+            throw new Error(`user_data_inventory missing catalog id ${id}`);
+        }
+    }
+    return entries;
+}
+export function parseV2HandoffManifest(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("manifest must be a JSON object");
+    }
+    const schemaVersion = asNonEmptyString(raw.schema_version, "schema_version");
+    if (schemaVersion !== V2_HANDOFF_SCHEMA_VERSION) {
+        throw new Error(`schema_version must be ${V2_HANDOFF_SCHEMA_VERSION}`);
+    }
+    const writtenAt = asNonEmptyString(raw.written_at, "written_at");
+    if (Number.isNaN(Date.parse(writtenAt))) {
+        throw new Error("written_at must be an ISO-8601 UTC timestamp");
+    }
+    if (!Array.isArray(raw.runtime_adapters)) {
+        throw new Error("runtime_adapters must be an array");
+    }
+    const runtimeAdapters = raw.runtime_adapters.map((adapter, index) => asNonEmptyString(adapter, `runtime_adapters[${index}]`));
+    return {
+        schema_version: V2_HANDOFF_SCHEMA_VERSION,
+        written_at: writtenAt,
+        installed_v2_version: asNonEmptyString(raw.installed_v2_version, "installed_v2_version"),
+        app_home_path: asNonEmptyString(raw.app_home_path, "app_home_path"),
+        user_data_inventory: parseUserDataInventory(raw.user_data_inventory),
+        runtime_adapters: runtimeAdapters,
+    };
+}
+export function v2HandoffManifestPath(appHome) {
+    return path.join(resolvePath(appHome), V2_HANDOFF_MANIFEST_FILENAME);
+}
+export function readV2HandoffManifestFile(appHome) {
+    const manifestPath = v2HandoffManifestPath(appHome);
+    if (!isFile(manifestPath)) {
+        return null;
+    }
+    const started = performance.now();
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    }
+    catch (exc) {
+        throw new Error(`failed to read ${V2_HANDOFF_MANIFEST_FILENAME}: ${exc.message}`);
+    }
+    const manifest = parseV2HandoffManifest(parsed);
+    const elapsedMs = performance.now() - started;
+    return { manifest, elapsedMs };
+}
+function agenteraUserStateDirIsRecognized(dir) {
+    if (!pathExists(dir) || !fs.statSync(dir).isDirectory()) {
+        return false;
+    }
+    for (const entry of fs.readdirSync(dir)) {
+        const full = path.join(dir, entry);
+        const st = fs.statSync(full);
+        if (AGENTERA_USER_STATE_NAMES.has(entry) && st.isFile()) {
+            continue;
+        }
+        if (entry === "optimera" && st.isDirectory()) {
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+function isPreservedUserStateEntry(appHome, entry) {
+    const full = path.join(appHome, entry);
+    if (!pathExists(full)) {
+        return false;
+    }
+    const st = fs.statSync(full);
+    if (ROOT_USER_STATE_FILE_NAMES.has(entry) && st.isFile()) {
+        return true;
+    }
+    if (ROOT_USER_STATE_DIR_NAMES.has(entry) && st.isDirectory()) {
+        return true;
+    }
+    if (entry === ".agentera" && agenteraUserStateDirIsRecognized(full)) {
+        return true;
+    }
+    if (USER_DATA_CATALOG_DIRS.includes(entry) &&
+        st.isDirectory()) {
+        return true;
+    }
+    return false;
+}
+function listPreservedTopLevelFromScan(appHome) {
+    if (!pathExists(appHome)) {
+        return [];
+    }
+    const preserved = [];
+    for (const entry of fs.readdirSync(appHome)) {
+        if (entry === "app" || entry === V2_HANDOFF_MANIFEST_FILENAME) {
+            continue;
+        }
+        if (isPreservedUserStateEntry(appHome, entry)) {
+            preserved.push(entry);
+        }
+    }
+    return preserved.sort();
+}
+function listPreservedAbsolutePathsFromScan(appHome) {
+    const preserved = [];
+    for (const entry of listPreservedTopLevelFromScan(appHome)) {
+        const full = path.join(appHome, entry);
+        preserved.push(full);
+        if (entry === ".agentera" && pathExists(full) && fs.statSync(full).isDirectory()) {
+            for (const name of AGENTERA_USER_STATE_NAMES) {
+                const nested = path.join(full, name);
+                if (isFile(nested)) {
+                    preserved.push(nested);
+                }
+            }
+        }
+    }
+    return preserved.sort();
+}
+function listPreservedTopLevelFromManifest(manifest) {
+    const preserved = new Set();
+    for (const entry of manifest.user_data_inventory) {
+        if (entry.kind === "directory" && entry.exists) {
+            preserved.add(entry.relative_path);
+        }
+        if (entry.kind === "profile_files") {
+            for (const member of entry.members) {
+                if (member.exists) {
+                    preserved.add(member.relative_path);
+                }
+            }
+        }
+    }
+    return [...preserved].sort();
+}
+function listPreservedAbsolutePathsFromManifest(manifest, appHome) {
+    const root = resolvePath(appHome);
+    const preserved = [];
+    for (const rel of listPreservedTopLevelFromManifest(manifest)) {
+        preserved.push(path.join(root, rel));
+    }
+    const agenteraDir = path.join(root, ".agentera");
+    if (pathExists(agenteraDir) && fs.statSync(agenteraDir).isDirectory()) {
+        preserved.push(agenteraDir);
+        for (const name of AGENTERA_USER_STATE_NAMES) {
+            const nested = path.join(agenteraDir, name);
+            if (isFile(nested)) {
+                preserved.push(nested);
+            }
+        }
+    }
+    return preserved.sort();
+}
+export function isManifestCatalogEntryPreserved(manifest, entry) {
+    for (const item of manifest.user_data_inventory) {
+        if (item.kind === "directory" && item.relative_path === entry) {
+            return item.exists;
+        }
+        if (item.kind === "profile_files") {
+            for (const member of item.members) {
+                if (member.relative_path === entry) {
+                    return member.exists;
+                }
+            }
+        }
+    }
+    if (entry === ".agentera") {
+        const agenteraDir = path.join(resolvePath(manifest.app_home_path), ".agentera");
+        return agenteraUserStateDirIsRecognized(agenteraDir);
+    }
+    return false;
+}
+export function resolveMigrationUserStatePreflight(appHome) {
+    const resolvedHome = resolvePath(appHome);
+    const manifestRead = readV2HandoffManifestFile(resolvedHome);
+    if (manifestRead) {
+        return {
+            source: "manifest",
+            elapsedMs: manifestRead.elapsedMs,
+            manifest: manifestRead.manifest,
+            preservedTopLevel: listPreservedTopLevelFromManifest(manifestRead.manifest),
+            preservedAbsolutePaths: listPreservedAbsolutePathsFromManifest(manifestRead.manifest, resolvedHome),
+        };
+    }
+    const started = performance.now();
+    const preservedTopLevel = listPreservedTopLevelFromScan(resolvedHome);
+    const preservedAbsolutePaths = listPreservedAbsolutePathsFromScan(resolvedHome);
+    return {
+        source: "scan",
+        elapsedMs: performance.now() - started,
+        manifest: null,
+        preservedTopLevel,
+        preservedAbsolutePaths,
+    };
+}
+export function appHomeHasUnrecognizedEntriesWithPreflight(appHome, preflight) {
+    if (!pathExists(appHome)) {
+        return [];
+    }
+    const unknown = [];
+    for (const entry of fs.readdirSync(appHome)) {
+        if (entry === "app" || entry === V2_HANDOFF_MANIFEST_FILENAME) {
+            continue;
+        }
+        if (preflight.source === "manifest" && preflight.manifest) {
+            if (isManifestCatalogEntryPreserved(preflight.manifest, entry)) {
+                continue;
+            }
+        }
+        else if (isPreservedUserStateEntry(appHome, entry)) {
+            continue;
+        }
+        unknown.push(entry);
+    }
+    return unknown;
+}
+export function isV2HandoffManifestStale(manifest, ctx) {
+    if (resolvePath(manifest.app_home_path) !== resolvePath(ctx.appHome)) {
+        return true;
+    }
+    if (manifest.installed_v2_version !== ctx.installedVersion) {
+        return true;
+    }
+    const writtenAtMs = Date.parse(manifest.written_at);
+    const markerMs = ctx.bundleMarkerMtimeMs;
+    if (Number.isNaN(writtenAtMs) || Math.floor(writtenAtMs / 1000) < Math.floor(markerMs / 1000)) {
+        return true;
+    }
+    return false;
+}
+export function bundleMarkerFreshnessContext(appHome, sourceRoot) {
+    const roots = doctorRoots(appHome);
+    const markerPath = path.join(roots.activeBundleRoot, ".agentera-bundle.json");
+    if (!isFile(markerPath)) {
+        return null;
+    }
+    const installedVersion = loadSuiteVersion(roots.activeBundleRoot) ?? loadSuiteVersion(sourceRoot) ?? "unknown";
+    return {
+        appHome: resolvePath(appHome),
+        installedVersion,
+        bundleMarkerMtimeMs: fs.statSync(markerPath).mtimeMs,
+    };
+}
+//# sourceMappingURL=v2HandoffManifest.js.map

package/dist/migrate/v2HandoffManifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2HandoffManifest.js","sourceRoot":"","sources":["../../src/migrate/v2HandoffManifest.ts"],"names":[],"mappings":"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"}

package/dist/registries/artifactProtocolIds.js

@@ -0,0 +1,77 @@
+/**
+ * Decision 58 artifact protocol names: one `artifact_id` per artifact in CLI,
+ * hooks, validators, and JSON envelopes. Storage paths live here only.
+ */
+export const ARTIFACT_PROTOCOL_PATHS = {
+    vision: ".agentera/vision.yaml",
+    decisions: ".agentera/decisions.yaml",
+    plan: ".agentera/plan.yaml",
+    progress: ".agentera/progress.yaml",
+    health: ".agentera/health.yaml",
+    docs: ".agentera/docs.yaml",
+    objective: ".agentera/objective.yaml",
+    experiments: ".agentera/experiments.yaml",
+    todo: "TODO.md",
+    changelog: "CHANGELOG.md",
+    design: "DESIGN.md",
+};
+export const HUMAN_FACING_ARTIFACT_IDS = new Set(["todo", "changelog", "design"]);
+export const TRACKED_ARTIFACT_IDS = [
+    "progress",
+    "decisions",
+    "plan",
+    "health",
+    "design",
+    "docs",
+    "vision",
+    "todo",
+    "changelog",
+];
+export const VALIDATE_ARTIFACT_PROTOCOL_IDS = [
+    "changelog",
+    "decisions",
+    "design",
+    "docs",
+    "health",
+    "plan",
+    "progress",
+    "todo",
+    "vision",
+];
+function artifactProtocolStem(input) {
+    const lower = input.trim().toLowerCase();
+    return lower.endsWith(".md") ? lower.slice(0, -3) : lower;
+}
+export function normalizeArtifactProtocolId(input) {
+    const trimmed = input.trim();
+    if (trimmed in ARTIFACT_PROTOCOL_PATHS) {
+        return trimmed;
+    }
+    const lower = trimmed.toLowerCase();
+    if (lower in ARTIFACT_PROTOCOL_PATHS) {
+        return lower;
+    }
+    const stem = artifactProtocolStem(trimmed);
+    if (stem in ARTIFACT_PROTOCOL_PATHS) {
+        return stem;
+    }
+    return null;
+}
+export function requireArtifactProtocolId(input, context) {
+    const id = normalizeArtifactProtocolId(input);
+    if (id === null) {
+        const valid = VALIDATE_ARTIFACT_PROTOCOL_IDS.join(", ");
+        throw new Error(`unsupported artifact ${JSON.stringify(input)} in ${context}; valid artifact_id values: ${valid}`);
+    }
+    return id;
+}
+/** Normalize docs.yaml mapping keys to artifact_id. */
+export function normalizeArtifactMappingKeys(mapping) {
+    const out = {};
+    for (const [key, value] of Object.entries(mapping)) {
+        const id = normalizeArtifactProtocolId(key);
+        out[id ?? key] = value;
+    }
+    return out;
+}
+//# sourceMappingURL=artifactProtocolIds.js.map

package/dist/registries/artifactProtocolIds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactProtocolIds.js","sourceRoot":"","sources":["../../src/registries/artifactProtocolIds.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAqC;IACvE,MAAM,EAAE,uBAAuB;IAC/B,SAAS,EAAE,0BAA0B;IACrC,IAAI,EAAE,qBAAqB;IAC3B,QAAQ,EAAE,yBAAyB;IACnC,MAAM,EAAE,uBAAuB;IAC/B,IAAI,EAAE,qBAAqB;IAC3B,SAAS,EAAE,0BAA0B;IACrC,WAAW,EAAE,4BAA4B;IACzC,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,cAAc;IACzB,MAAM,EAAE,WAAW;CACpB,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAElF,MAAM,CAAC,MAAM,oBAAoB,GAAsB;IACrD,UAAU;IACV,WAAW;IACX,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,MAAM;IACN,WAAW;CACZ,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAAsB;IAC/D,WAAW;IACX,WAAW;IACX,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,MAAM;IACN,UAAU;IACV,MAAM;IACN,QAAQ;CACT,CAAC;AAEF,SAAS,oBAAoB,CAAC,KAAa;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACzC,OAAO,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,KAAa;IACvD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,IAAI,uBAAuB,EAAE,CAAC;QACvC,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,IAAI,KAAK,IAAI,uBAAuB,EAAE,CAAC;QACrC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,IAAI,IAAI,uBAAuB,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAa,EAAE,OAAe;IACtE,MAAM,EAAE,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAChB,MAAM,KAAK,GAAG,8BAA8B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,OAAO,+BAA+B,KAAK,EAAE,CAAC,CAAC;IACrH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,4BAA4B,CAAC,OAA+B;IAC1E,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,MAAM,EAAE,GAAG,2BAA2B,CAAC,GAAG,CAAC,CAAC;QAC5C,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC;IACzB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/release/releaseMetadata.js

@@ -0,0 +1,235 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolvePath } from "../core/paths.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadYamlMappingFile } from "../core/yaml.js";
+export const RELEASE_METADATA_AUTHORITY_FILES = [
+    "registry.json",
+    "packages/cli/package.json",
+    "references/cli/update-channels.yaml",
+];
+export const RELEASE_METADATA_ADVISORY_FILES = [
+    "packages/cli/bundle/.agentera-npx-bundle.json",
+];
+const SEMVER_CORE_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const SEMVER_STRICT_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const PRE_RELEASE_RE = /-(.+)$/;
+const GIT_REF_HEX_RE = /^[0-9a-f]{40}$/i;
+function rootDefault() {
+    return resolveSourceRoot();
+}
+function readJson(pathname) {
+    try {
+        return JSON.parse(fs.readFileSync(pathname, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function readRegistryVersion(root) {
+    const source = "registry.json";
+    const data = readJson(path.join(root, source));
+    if (data === null) {
+        return { version: null, source };
+    }
+    const skills = data.skills;
+    if (!Array.isArray(skills) || skills.length === 0) {
+        return { version: null, source };
+    }
+    const first = skills[0];
+    if (!first || typeof first !== "object") {
+        return { version: null, source };
+    }
+    const version = first.version;
+    return { version: typeof version === "string" ? version : null, source };
+}
+function readPackageJson(root) {
+    const candidate = path.join(root, "packages/cli/package.json");
+    if (!fs.existsSync(candidate)) {
+        return null;
+    }
+    return readJson(candidate);
+}
+function readUpdateChannels(root) {
+    const candidate = path.join(root, "references/cli/update-channels.yaml");
+    if (!fs.existsSync(candidate)) {
+        return null;
+    }
+    try {
+        return loadYamlMappingFile(candidate);
+    }
+    catch {
+        return null;
+    }
+}
+function readBundleSentinel(root) {
+    const source = "packages/cli/bundle/.agentera-npx-bundle.json";
+    const candidate = path.join(root, source);
+    if (!fs.existsSync(candidate)) {
+        return { version: null, source };
+    }
+    const data = readJson(candidate);
+    if (data === null) {
+        return { version: null, source };
+    }
+    const version = data.suiteVersion;
+    return { version: typeof version === "string" ? version : null, source };
+}
+/** Parse `X.Y.Z` core (ignore pre-release and build metadata). */
+function parseSemverCore(version) {
+    const match = SEMVER_CORE_RE.exec(version);
+    if (!match) {
+        return null;
+    }
+    const core = `${match[1]}.${match[2]}.${match[3]}`;
+    const preMatch = PRE_RELEASE_RE.exec(version);
+    return { core, preRelease: preMatch ? preMatch[1] : null };
+}
+function pickChannelDefaults(authority) {
+    if (authority === null) {
+        return { development: null, stable: null };
+    }
+    const versionResolution = authority.version_resolution;
+    const latestOnChannel = versionResolution?.latest_on_channel;
+    const defaults = (latestOnChannel?.offline_defaults ?? {});
+    return {
+        development: typeof defaults.development === "string" ? defaults.development : null,
+        stable: typeof defaults.stable === "string" ? defaults.stable : null,
+    };
+}
+export function readReleaseMetadata(root = rootDefault()) {
+    const resolved = resolvePath(root);
+    const registry = readRegistryVersion(resolved);
+    const pkg = readPackageJson(resolved);
+    const channels = readUpdateChannels(resolved);
+    const bundle = readBundleSentinel(resolved);
+    const topVersion = pkg && typeof pkg.version === "string" ? pkg.version : null;
+    const agenteraBlock = pkg && typeof pkg.agentera === "object" && pkg.agentera !== null
+        ? pkg.agentera
+        : null;
+    const suiteVersion = agenteraBlock && typeof agenteraBlock.suiteVersion === "string"
+        ? agenteraBlock.suiteVersion
+        : null;
+    const gitRef = agenteraBlock && typeof agenteraBlock.gitRef === "string"
+        ? agenteraBlock.gitRef
+        : null;
+    const { development, stable } = pickChannelDefaults(channels);
+    return {
+        authoritativeVersion: registry.version,
+        authoritativeSource: registry.source,
+        packageVersion: topVersion,
+        packageSuiteVersion: suiteVersion,
+        packageGitRef: gitRef,
+        developmentChannelDefault: development,
+        stableChannelDefault: stable,
+        bundleSuiteVersion: bundle.version,
+    };
+}
+/**
+ * Validate release-metadata coherence. Returns an empty array when the
+ * source-tree version surfaces agree on a single release train.
+ */
+export function validateReleaseMetadata(root = rootDefault()) {
+    const errors = [];
+    const snap = readReleaseMetadata(root);
+    const rootLabel = path.basename(resolvePath(root)) || "repo root";
+    // 1. registry.json must publish a valid semver `skills[0].version`.
+    if (snap.authoritativeVersion === null) {
+        errors.push("registry.json: skills[0].version is required for release-metadata validation");
+    }
+    else {
+        const parsed = parseSemverCore(snap.authoritativeVersion);
+        if (parsed === null) {
+            errors.push(`registry.json: skills[0].version ${JSON.stringify(snap.authoritativeVersion)} is not a valid semver`);
+        }
+        else if (parsed.preRelease !== null) {
+            // registry.json is the suite authority and stays on the released core;
+            // pre-release suffixes belong only to packages/cli/package.json.
+            errors.push(`registry.json: skills[0].version must be a released core version (no pre-release suffix); got ${JSON.stringify(snap.authoritativeVersion)}`);
+        }
+    }
+    // 2. packages/cli/package.json must exist and parse.
+    if (snap.packageVersion === null && snap.packageSuiteVersion === null && snap.packageGitRef === null) {
+        errors.push("packages/cli/package.json: missing or unreadable; cannot validate release-metadata");
+    }
+    else {
+        // 2a. top-level `version` must be valid semver and share its core with registry.
+        if (snap.packageVersion === null) {
+            errors.push("packages/cli/package.json: top-level `version` is required");
+        }
+        else {
+            const parsed = parseSemverCore(snap.packageVersion);
+            if (parsed === null) {
+                errors.push(`packages/cli/package.json: top-level version ${JSON.stringify(snap.packageVersion)} is not a valid semver`);
+            }
+            else if (snap.authoritativeVersion !== null &&
+                parseSemverCore(snap.authoritativeVersion)?.core !== parsed.core) {
+                errors.push(`release-metadata divergence: registry.json skills[0].version core is ${JSON.stringify(parseSemverCore(snap.authoritativeVersion)?.core)} ` +
+                    `but packages/cli/package.json top-level version core is ${JSON.stringify(parsed.core)}; ` +
+                    `the npm package version must share its major.minor.patch with the registry suite version`);
+            }
+        }
+        // 2b. `agentera.suiteVersion` must match registry exactly.
+        if (snap.packageSuiteVersion === null) {
+            errors.push("packages/cli/package.json: `agentera.suiteVersion` is required");
+        }
+        else if (snap.authoritativeVersion !== null &&
+            snap.packageSuiteVersion !== snap.authoritativeVersion) {
+            errors.push(`release-metadata divergence: registry.json skills[0].version is ${JSON.stringify(snap.authoritativeVersion)} ` +
+                `but packages/cli/package.json agentera.suiteVersion is ${JSON.stringify(snap.packageSuiteVersion)}; ` +
+                `the agentera.suiteVersion mirror must equal the registry version exactly`);
+        }
+        else if (!SEMVER_STRICT_RE.test(snap.packageSuiteVersion)) {
+            errors.push(`packages/cli/package.json: agentera.suiteVersion ${JSON.stringify(snap.packageSuiteVersion)} is not a released core semver`);
+        }
+        // 2c. `agentera.gitRef` must be a 40-character hex SHA.
+        if (snap.packageGitRef === null || snap.packageGitRef === "") {
+            errors.push("packages/cli/package.json: `agentera.gitRef` is required for release-metadata validation");
+        }
+        else if (!GIT_REF_HEX_RE.test(snap.packageGitRef)) {
+            errors.push(`packages/cli/package.json: agentera.gitRef ${JSON.stringify(snap.packageGitRef)} must be a 40-character hex SHA; ` +
+                `short SHAs and branch names are not reproducible release references`);
+        }
+    }
+    // 3. update-channels.yaml development default must equal the registry version.
+    if (snap.developmentChannelDefault === null) {
+        errors.push("references/cli/update-channels.yaml: version_resolution.latest_on_channel.offline_defaults.development is required");
+    }
+    else if (snap.authoritativeVersion !== null &&
+        snap.developmentChannelDefault !== snap.authoritativeVersion) {
+        errors.push(`release-metadata divergence: registry.json skills[0].version is ${JSON.stringify(snap.authoritativeVersion)} ` +
+            `but update-channels.yaml offline_defaults.development is ${JSON.stringify(snap.developmentChannelDefault)}; ` +
+            `the development channel default must match the registry version exactly`);
+    }
+    // 4. Stable channel default is informational on the @next branch; the
+    // validator surfaces it so maintainers can confirm the stable line still
+    // resolves to its declared 2.x version. A drift on the stable channel
+    // alone is not an error here — that lane is owned by the `main` branch
+    // compatibility boundary per `references/cli/update-channels.yaml`.
+    void snap.stableChannelDefault;
+    // 5. Advisory check on the local bundle sentinel.
+    if (snap.bundleSuiteVersion !== null) {
+        if (snap.authoritativeVersion !== null &&
+            snap.bundleSuiteVersion !== snap.authoritativeVersion) {
+            errors.push(`release-metadata drift (advisory): packages/cli/bundle/.agentera-npx-bundle.json suiteVersion is ${JSON.stringify(snap.bundleSuiteVersion)} ` +
+                `but registry.json skills[0].version is ${JSON.stringify(snap.authoritativeVersion)}; ` +
+                `run \`npm run bundle:data\` (or \`pnpm -C packages/cli run bundle:data\`) at ${rootLabel} to refresh the local bundle copy before publishing`);
+        }
+    }
+    return errors;
+}
+export function releaseMetadataMain(opts = {}) {
+    const root = resolvePath(opts.root ?? rootDefault());
+    const out = opts.out ?? ((line) => process.stdout.write(line + "\n"));
+    const err = opts.err ?? ((line) => process.stderr.write(line + "\n"));
+    const errors = validateReleaseMetadata(root);
+    if (errors.length > 0) {
+        out("release-metadata validation failed:");
+        for (const message of errors)
+            out(`- ${message}`);
+        return 1;
+    }
+    out("release-metadata ok");
+    return 0;
+}
+//# sourceMappingURL=releaseMetadata.js.map