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

package/dist/upgrade/migrationPublication.js

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+import { observeLifecyclePath, publishLifecycleResource, removeLifecycleResource, verifyLifecycleResourceAtPublication, withPinnedLifecycleDirectory, } from "../runtime/lifecyclePublication.js";
+const evidenceByItem = new WeakMap();
+const MIGRATION_EVIDENCE = Symbol.for("agentera.migrationMutationEvidence");
+function evidenceFor(item) {
+    const existing = evidenceByItem.get(item) ?? item[MIGRATION_EVIDENCE];
+    if (existing)
+        return existing;
+    const created = { resources: {} };
+    evidenceByItem.set(item, created);
+    item[MIGRATION_EVIDENCE] = created;
+    return created;
+}
+function readEvidence(item) {
+    return evidenceByItem.get(item) ?? item[MIGRATION_EVIDENCE];
+}
+export function cloneMigrationItem(item) {
+    const clone = { ...item };
+    const evidence = readEvidence(item);
+    if (evidence) {
+        evidenceByItem.set(clone, evidence);
+        clone[MIGRATION_EVIDENCE] = evidence;
+    }
+    return clone;
+}
+function observationError(destination, observation, expectedKind) {
+    if (observation.unsafeReason)
+        return observation.unsafeReason;
+    if (!observation.parentComplete)
+        return `parent chain is incomplete for ${destination}`;
+    if (observation.kind !== expectedKind || !observation.identity || !observation.fingerprint) {
+        return `${destination} is not an observable ${expectedKind}`;
+    }
+    return null;
+}
+export function bindMigrationResource(item, role, destination, allowedRoots, kind) {
+    const observation = observeLifecyclePath(destination, allowedRoots);
+    const error = observationError(destination, observation, kind);
+    if (error)
+        return error;
+    evidenceFor(item).resources[role] = { destination, kind, observation };
+    return null;
+}
+function boundResource(item, role) {
+    const resource = readEvidence(item)?.resources[role];
+    if (!resource)
+        throw new Error(`migration ${role} publication evidence is missing`);
+    return resource;
+}
+export function verifyBoundMigrationResource(item, role) {
+    const resource = boundResource(item, role);
+    verifyLifecycleResourceAtPublication({ id: `${item.action}.${role}`, destination: resource.destination, kind: resource.kind }, resource.observation);
+}
+export function withBoundMigrationDirectory(item, role, callback, hook) {
+    const resource = boundResource(item, role);
+    if (resource.kind !== "directory")
+        throw new Error(`migration ${role} is not a directory`);
+    return withPinnedLifecycleDirectory({ id: `${item.action}.${role}`, destination: resource.destination, kind: "directory" }, resource.observation, callback, hook);
+}
+export function updateBoundMigrationFile(item, role, content) {
+    const resource = boundResource(item, role);
+    if (resource.kind !== "file")
+        throw new Error(`migration ${role} is not a file`);
+    publishLifecycleResource({ id: `${item.action}.${role}`, destination: resource.destination, kind: "file", content }, "update", resource.observation);
+}
+export function removeBoundMigrationResource(item, role) {
+    const resource = boundResource(item, role);
+    removeLifecycleResource({ id: `${item.action}.${role}`, destination: resource.destination, kind: resource.kind }, resource.observation);
+}
+function walkTree(root) {
+    const entries = [];
+    const walk = (destination) => {
+        const stat = fs.lstatSync(destination);
+        const kind = stat.isSymbolicLink()
+            ? "symlink"
+            : stat.isFile()
+                ? "file"
+                : stat.isDirectory()
+                    ? "directory"
+                    : (() => { throw new Error(`unsupported bundle entry type at ${destination}`); })();
+        entries.push({ destination, kind });
+        if (kind === "directory") {
+            for (const name of fs.readdirSync(destination).sort())
+                walk(path.join(destination, name));
+        }
+    };
+    walk(root);
+    return entries;
+}
+export function bindMigrationTree(item, root, allowedRoots) {
+    try {
+        const tree = walkTree(root).map(({ destination, kind }) => {
+            const observation = observeLifecyclePath(destination, allowedRoots);
+            const error = observationError(destination, observation, kind);
+            if (error)
+                throw new Error(error);
+            return { destination, kind, observation };
+        });
+        evidenceFor(item).tree = tree;
+        return null;
+    }
+    catch (error) {
+        return error.message;
+    }
+}
+export function removeBoundMigrationTree(item) {
+    const tree = readEvidence(item)?.tree;
+    if (!tree)
+        throw new Error("migration cleanup tree evidence is missing");
+    const current = walkTree(tree[0].destination);
+    if (current.length !== tree.length
+        || current.some((entry, index) => entry.destination !== tree[index]?.destination || entry.kind !== tree[index]?.kind)) {
+        throw new Error("managed app cleanup set changed after preview");
+    }
+    for (const entry of tree) {
+        verifyLifecycleResourceAtPublication({ id: `${item.action}.verify`, destination: entry.destination, kind: entry.kind }, entry.observation);
+    }
+    for (const entry of [...tree].reverse()) {
+        removeLifecycleResource({ id: `${item.action}.remove`, destination: entry.destination, kind: entry.kind }, entry.observation);
+    }
+}

package/dist/upgrade/nextMajorDoctor.js

@@ -0,0 +1,155 @@
+import { cliDistributionMajor } from "./compatibility.js";
+import { loadUpdateChannelsAuthority, resolveSelectedChannel, } from "./channels.js";
+import { resolveRunningVersion } from "./versionResolution.js";
+/**
+ * Head-of-output "next major" doctor section.
+ * Authority: references/cli/update-channels.yaml (channels.<channel>.next_major)
+ */
+export const NEXT_MAJOR_SECTION_HEADER = "Next major";
+export const NEXT_MAJOR_LINE_CAP = 6;
+/** v1 installs predate the channel authority; hardcoded stable-line successor mapping. */
+export const V1_NEXT_MAJOR_FALLBACK = {
+    concept: "forward_successor_line",
+    currentVersion: "1.x",
+    currentChannel: "stable",
+    channel: "stable",
+    version: "2.x",
+    announced: true,
+    npmOnlyAdvisory: "",
+    guideUrl: "https://github.com/jgabor/agentera/blob/main/UPGRADE.md#recommended-upgrade-v1--v2-stable-channel",
+    previewCommand: "npx -y agentera@latest upgrade --dry-run",
+    irreversibleAdvisory: "Forward migration upgrades artifact format from Markdown to YAML; review the preview before applying.",
+};
+function parseNextMajorBlock(raw) {
+    if (raw === null || raw === undefined) {
+        return null;
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return null;
+    }
+    const block = raw;
+    const channel = String(block.channel ?? "").trim().toLowerCase();
+    if (channel !== "stable" && channel !== "development") {
+        return null;
+    }
+    const version = String(block.version ?? "").trim();
+    if (!version) {
+        return null;
+    }
+    const guideUrl = String(block.guide_url ?? "").trim();
+    const previewCommand = String(block.preview_command ?? "").trim();
+    const irreversibleAdvisory = String(block.irreversible_advisory ?? "").trim();
+    if (!guideUrl || !previewCommand || !irreversibleAdvisory) {
+        return null;
+    }
+    return {
+        concept: String(block.concept ?? "forward_successor_line").trim(),
+        channel: channel,
+        version,
+        announced: block.announced !== false,
+        npmOnlyAdvisory: String(block.npm_only_advisory ?? "").trim(),
+        guideUrl,
+        previewCommand,
+        irreversibleAdvisory,
+    };
+}
+let testSuccessorAnnouncedOverride = null;
+/** Reset injectable successor announcement gate (tests). */
+export function setSuccessorAnnouncedOverrideForTests(value) {
+    testSuccessorAnnouncedOverride = value;
+}
+/**
+ * True when the resolved channel's successor metadata exists and is announced
+ * for doctor/prime. Defaults to the stable channel so legacy callers that
+ * omit the argument behave identically to pre-fix behavior.
+ */
+export function isStableSuccessorAnnounced(sourceRoot, channel = "stable") {
+    if (testSuccessorAnnouncedOverride !== null) {
+        return testSuccessorAnnouncedOverride;
+    }
+    const block = loadChannelNextMajor(sourceRoot, channel);
+    return block?.announced === true;
+}
+export function loadChannelNextMajor(sourceRoot, channel) {
+    const authority = loadUpdateChannelsAuthority(sourceRoot);
+    const channels = authority.channels;
+    const entry = channels?.[channel];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return null;
+    }
+    return parseNextMajorBlock(entry.next_major);
+}
+export function formatNextMajorDoctorLines(args) {
+    const nextLine = args.block.npmOnlyAdvisory
+        ? `Next: ${args.block.version} (${args.block.channel} channel). ${args.block.npmOnlyAdvisory}`
+        : `Next: ${args.block.version} (${args.block.channel} channel)`;
+    return [
+        NEXT_MAJOR_SECTION_HEADER,
+        `Current: ${args.currentVersion} (${args.currentChannel} channel)`,
+        nextLine,
+        `Guide: ${args.block.guideUrl}`,
+        `Preview: ${args.block.previewCommand}`,
+        args.block.irreversibleAdvisory,
+    ];
+}
+function installTrackSkipsSuccessorBlock(install, sourceRoot) {
+    if (install?.kind === "v3_self_contained_npm") {
+        return true;
+    }
+    if (install?.kind === "source_checkout" && cliDistributionMajor(sourceRoot) >= 3) {
+        return true;
+    }
+    return false;
+}
+export function resolveNextMajorDoctorLines(ctx) {
+    const env = ctx.env ?? process.env;
+    const home = ctx.home;
+    const sourceRoot = ctx.sourceRoot;
+    const install = ctx.install ?? null;
+    if (installTrackSkipsSuccessorBlock(install, sourceRoot)) {
+        return null;
+    }
+    const selected = resolveSelectedChannel({
+        channel: ctx.channel ?? null,
+        env,
+        home,
+        sourceRoot,
+    });
+    const currentChannel = selected.channel;
+    const successorChannel = install?.kind === "v2_managed_app_home" ? "stable" : currentChannel;
+    const displayChannel = install?.kind === "v2_managed_app_home" ? "stable" : currentChannel;
+    const runningDistributionMajor = ctx.runningDistributionMajor ??
+        (install?.kind === "v2_managed_app_home" ? 2 : cliDistributionMajor(sourceRoot));
+    if (runningDistributionMajor === 1) {
+        const block = V1_NEXT_MAJOR_FALLBACK;
+        return formatNextMajorDoctorLines({
+            currentVersion: block.currentVersion,
+            currentChannel: block.currentChannel,
+            block,
+        });
+    }
+    const authorityBlock = loadChannelNextMajor(sourceRoot, successorChannel);
+    if (!authorityBlock || !authorityBlock.announced) {
+        return null;
+    }
+    const runningVersion = ctx.runningVersion ??
+        (install
+            ? resolveRunningVersion({
+                appHome: install.appHome,
+                sourceRoot,
+                install,
+            })
+            : null) ??
+        `${runningDistributionMajor}.x`;
+    return formatNextMajorDoctorLines({
+        currentVersion: runningVersion,
+        currentChannel: displayChannel,
+        block: authorityBlock,
+    });
+}
+export function prependNextMajorDoctorSection(text, sectionLines) {
+    if (!sectionLines || sectionLines.length === 0) {
+        return text;
+    }
+    return `${sectionLines.join("\n")}\n\n${text}`;
+}

package/dist/upgrade/npxPlatformStatus.js

@@ -0,0 +1,22 @@
+import { expanduser } from "../core/paths.js";
+import { resolvePlatformAppHome } from "./appModel.js";
+import { buildDoctorStatus } from "./doctor.js";
+/** Shared npx platform app-home resolution for prime and projectIntegration. */
+export function resolveNpxPlatformStatus(opts) {
+    const env = { ...process.env, ...(opts.env ?? {}), HOME: expanduser(opts.home) };
+    const platformRoot = resolvePlatformAppHome(opts.home, env);
+    const doctorOpts = {
+        rootSource: "default",
+        sourceRoot: opts.sourceRoot,
+        home: opts.home,
+        project: opts.project,
+        expectedCommands: opts.expectedCommands ?? ["prime"],
+        skipNpxBundleShortCircuit: true,
+        env,
+    };
+    if (opts.expectedVersion !== undefined) {
+        doctorOpts.expectedVersion = opts.expectedVersion;
+    }
+    const platformStatus = buildDoctorStatus(platformRoot, doctorOpts);
+    return { platformRoot, platformStatus };
+}