agentera 3.0.0-dev.7 → 3.0.0-dev.72

package/dist/upgrade/legacyAgentCleanup.js

@@ -1,8 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+import { createHash } from "node:crypto";
 import { isFile, pathExists, resolvePath } from "../core/paths.js";
 import { opencodeConfigDir } from "../setup/opencode.js";
+import { bindMigrationResource, removeBoundMigrationResource } from "./migrationPublication.js";
 export const REMOVE_LEGACY_AGENT_ACTION = "remove-legacy-agent";
+/** Literal marker v2 wrote into managed per-capability agent files. */
+const MANAGED_AGENT_MARKER = "<!-- agentera: managed -->";
 /** Closed set of v2 Swedish-verb agent files left orphaned after v3 single-agent copy (#20). */
 export const V2_SWEDISH_VERB_AGENT_FILES = [
     "dokumentera.md",
@@ -22,11 +26,124 @@ const V2_SWEDISH_VERB_AGENT_SET = new Set(V2_SWEDISH_VERB_AGENT_FILES);
 export function isV2SwedishVerbAgentFile(name) {
     return V2_SWEDISH_VERB_AGENT_SET.has(name);
 }
+/**
+ * Closed set of v2 English-named per-capability agent files replaced by the
+ * single v3 `agentera.md` primary agent. These shipped under `.cursor/agents`
+ * and `.opencode/agents` and must be removed when the managed marker is present.
+ */
+export const V2_ENGLISH_CAPABILITY_AGENT_FILES = [
+    "audit.md",
+    "build.md",
+    "design.md",
+    "discuss.md",
+    "document.md",
+    "optimize.md",
+    "orchestrate.md",
+    "plan.md",
+    "profile.md",
+    "research.md",
+    "status.md",
+    "vision.md",
+];
+const V2_ENGLISH_CAPABILITY_AGENT_SET = new Set(V2_ENGLISH_CAPABILITY_AGENT_FILES);
+export function isV2EnglishCapabilityAgentFile(name) {
+    return V2_ENGLISH_CAPABILITY_AGENT_SET.has(name);
+}
+function regularFileIdentity(filePath) {
+    try {
+        const stat = fs.lstatSync(filePath);
+        return stat.isFile() ? `${stat.dev}:${stat.ino}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+function managedAgentOwnership(filePath) {
+    const identity = regularFileIdentity(filePath);
+    if (!identity)
+        return null;
+    let body;
+    try {
+        body = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    if (!body.includes(MANAGED_AGENT_MARKER))
+        return null;
+    return {
+        kind: "managed-marker-file",
+        identity,
+        fingerprint: `sha256:${createHash("sha256").update(body).digest("hex")}`,
+    };
+}
+function planAgentFiles(ctx, names, description) {
+    const items = [];
+    for (const { runtime, agentsDir } of legacyAgentScanTargets(ctx)) {
+        let directory;
+        try {
+            directory = fs.lstatSync(agentsDir);
+        }
+        catch {
+            continue;
+        }
+        if (!directory.isDirectory()) {
+            items.push({
+                status: "blocked",
+                action: REMOVE_LEGACY_AGENT_ACTION,
+                runtime,
+                source: agentsDir,
+                message: `preserved ${agentsDir}: the legacy agents path is not a real directory; replace the unsafe path or review it manually`,
+            });
+            continue;
+        }
+        for (const name of names) {
+            const source = path.join(agentsDir, name);
+            let candidate;
+            try {
+                candidate = fs.lstatSync(source);
+            }
+            catch {
+                continue;
+            }
+            if (!candidate.isFile()) {
+                items.push({
+                    status: "blocked",
+                    action: REMOVE_LEGACY_AGENT_ACTION,
+                    runtime,
+                    source,
+                    message: `preserved ${source}: only a marker-owned regular file is eligible; review the unsafe resource manually`,
+                });
+                continue;
+            }
+            const ownership = managedAgentOwnership(source);
+            const item = {
+                status: ownership ? "pending" : "blocked",
+                action: REMOVE_LEGACY_AGENT_ACTION,
+                runtime,
+                source,
+                ...(ownership ? { ownership } : {}),
+                message: ownership
+                    ? `will remove marker-owned v2 ${description} ${name}`
+                    : `preserved ${source}: the legacy filename does not prove Agentera ownership; confirm ownership and remove it manually if appropriate`,
+            };
+            if (ownership) {
+                const evidenceError = bindMigrationResource(item, "source", source, [agentsDir], "file");
+                if (evidenceError) {
+                    item.status = "blocked";
+                    item.message = `preserved ${source}: ${evidenceError}; review the unsafe path manually`;
+                }
+            }
+            items.push(item);
+        }
+    }
+    return items;
+}
 export function legacyAgentScanTargets(ctx) {
     const project = resolvePath(ctx.project);
     const home = resolvePath(ctx.home);
     const appHome = resolvePath(ctx.appHome);
-    const env = ctx.env ?? process.env;
+    const env = ctx.env ?? { HOME: home };
     const targets = [];
     const seen = new Set();
     const push = (runtime, agentsDir) => {
@@ -61,6 +178,32 @@ export function scanLegacySwedishVerbAgentPaths(agentsDir) {
     }
     return hits.sort();
 }
+/**
+ * Scan an agents directory for v2 English-named per-capability agents that v3
+ * superseded with the single `agentera.md` primary agent. Only files carrying
+ * the managed marker are returned, so user-owned agents without the marker are
+ * preserved.
+ */
+export function scanLegacyCapabilityAgentPaths(agentsDir) {
+    if (!pathExists(agentsDir) || !fs.statSync(agentsDir).isDirectory()) {
+        return [];
+    }
+    const hits = [];
+    for (const name of fs.readdirSync(agentsDir)) {
+        if (!isV2EnglishCapabilityAgentFile(name)) {
+            continue;
+        }
+        const filePath = path.join(agentsDir, name);
+        if (!isFile(filePath)) {
+            continue;
+        }
+        const body = fs.readFileSync(filePath, "utf8");
+        if (body.includes(MANAGED_AGENT_MARKER)) {
+            hits.push(filePath);
+        }
+    }
+    return hits.sort();
+}
 /** Scan a tree for reintroduced Swedish-verb agents (v1LegacyCruft-style guard). */
 export function scanLegacySwedishVerbAgentViolations(root) {
     const resolved = resolvePath(root);
@@ -77,40 +220,63 @@ export function scanLegacySwedishVerbAgentViolations(root) {
     return violations.sort();
 }
 export function planLegacyAgentCleanupItems(ctx) {
-    const items = [];
-    for (const { runtime, agentsDir } of legacyAgentScanTargets(ctx)) {
-        for (const source of scanLegacySwedishVerbAgentPaths(agentsDir)) {
-            items.push({
-                status: "pending",
-                action: REMOVE_LEGACY_AGENT_ACTION,
-                runtime,
-                source,
-                message: `will remove orphaned v2 Swedish-verb agent ${path.basename(source)}`,
-            });
-        }
-    }
-    return items;
+    return planAgentFiles(ctx, V2_SWEDISH_VERB_AGENT_FILES, "Swedish-verb agent");
+}
+export function planLegacyCapabilityAgentCleanupItems(ctx) {
+    return planAgentFiles(ctx, V2_ENGLISH_CAPABILITY_AGENT_FILES, "per-capability agent");
 }
-export function applyLegacyAgentCleanupItems(items) {
+export function applyLegacyAgentCleanupItems(items, ctx) {
+    const allowed = new Set(legacyAgentScanTargets(ctx).map(({ agentsDir }) => path.resolve(agentsDir)));
     for (const item of items) {
         if (item.status !== "pending" || item.action !== REMOVE_LEGACY_AGENT_ACTION || !item.source) {
             continue;
         }
         const basename = path.basename(item.source);
         try {
-            if (!isV2SwedishVerbAgentFile(basename) || !isFile(item.source)) {
+            if (!allowed.has(path.dirname(path.resolve(item.source)))) {
+                item.status = "blocked";
+                item.message = `preserved ${item.source}: path is outside the legacy agent cleanup allowlist; review it manually`;
+                continue;
+            }
+            const ownership = managedAgentOwnership(item.source);
+            if (!ownership) {
+                let absent = false;
+                try {
+                    fs.lstatSync(item.source);
+                }
+                catch (error) {
+                    absent = error.code === "ENOENT";
+                }
+                if (absent) {
+                    item.status = "noop";
+                    item.message = `legacy agent already absent at ${item.source}`;
+                }
+                else {
+                    item.status = "blocked";
+                    item.message = `preserved ${item.source}: managed marker ownership is missing or unsafe; review it manually`;
+                }
+                continue;
+            }
+            if (item.ownership?.kind !== "managed-marker-file"
+                || item.ownership.identity !== ownership.identity
+                || item.ownership.fingerprint !== ownership.fingerprint) {
+                item.status = "blocked";
+                item.message = `preserved ${item.source}: ownership identity or fingerprint changed after preview; rerun migration and review the resource`;
+                continue;
+            }
+            if ((!isV2SwedishVerbAgentFile(basename) && !isV2EnglishCapabilityAgentFile(basename)) ||
+                !regularFileIdentity(item.source)) {
                 item.status = "noop";
                 item.message = `legacy agent already absent at ${item.source}`;
                 continue;
             }
-            fs.rmSync(item.source, { force: true });
+            removeBoundMigrationResource(item, "source");
             item.status = "applied";
-            item.message = `removed orphaned v2 Swedish-verb agent ${basename}`;
+            item.message = `removed orphaned v2 legacy agent ${basename}`;
         }
         catch (exc) {
-            item.status = "failed";
-            item.message = `${REMOVE_LEGACY_AGENT_ACTION} failed: ${exc.message}`;
+            item.status = "blocked";
+            item.message = `preserved ${item.source}: ${exc.message}; rerun migration and review it manually`;
         }
     }
 }
-//# sourceMappingURL=legacyAgentCleanup.js.map

package/dist/upgrade/lifecycleUpgrade.js

@@ -0,0 +1,113 @@
+import { appendLifecycleOwnershipJournal, lifecycleOwnershipJournalPath, readLifecycleOwnershipJournal, } from "../runtime/lifecycleOwnershipJournal.js";
+import { secureLifecycleRemovalAvailable } from "../runtime/lifecyclePublication.js";
+import { applyNativeResourceCleanup, previewNativeResourceCleanup, } from "../runtime/nativeResourceCleanup.js";
+export const LIFECYCLE_UPGRADE_SCHEMA = "agentera.lifecycleUpgrade.v1";
+function emptySummary() {
+    return {
+        applied: 0,
+        noop: 0,
+        failed: 0,
+        blocked_unowned: 0,
+        skipped_dependency: 0,
+        action_required: 0,
+        pending: 0,
+    };
+}
+function previewSummary(preview) {
+    const summary = emptySummary();
+    for (const operation of preview.plan.operations) {
+        if (operation.action === "noop")
+            summary.noop += 1;
+        else if (operation.action === "blocked_unowned")
+            summary.blocked_unowned += 1;
+        else if (operation.action === "action_required")
+            summary.action_required += 1;
+        else
+            summary.pending += 1;
+    }
+    return summary;
+}
+function resultSummary(result) {
+    return { ...result.summary, pending: 0 };
+}
+function blockedPlan(plan, reason) {
+    return {
+        ...plan,
+        operations: plan.operations.map((operation) => operation.action === "noop"
+            ? operation
+            : { ...operation, action: "action_required", reason }),
+    };
+}
+function journalBlocksMutation(journal) {
+    return !["absent", "clean"].includes(journal.state);
+}
+function journalBlocker(journal) {
+    const diagnostics = journal.diagnostics
+        .map((diagnostic) => diagnostic.replace(/^\d{20}-[0-9a-f-]{36}\.json:\s*/i, ""));
+    return `ownership journal is ${journal.state}: ${diagnostics.join("; ")}`;
+}
+function statusFor(mode, summary, requiredUnmet) {
+    if (summary.failed > 0
+        || summary.blocked_unowned > 0
+        || summary.skipped_dependency > 0
+        || summary.action_required > 0
+        || requiredUnmet.length > 0)
+        return "non_success";
+    if (mode === "preview" && summary.pending > 0)
+        return "pending";
+    if (mode === "apply" && summary.applied > 0)
+        return "success";
+    return "noop";
+}
+/** Preview or apply one explicit ownership-proven native Agentera resource cleanup. */
+export function runLifecycleUpgrade(args, options = {}) {
+    const journal = readLifecycleOwnershipJournal(lifecycleOwnershipJournalPath(args.appHome));
+    let preview = previewNativeResourceCleanup({
+        resourceId: args.resourceCleanup,
+        home: args.home,
+        ledger: journal.ledger,
+    });
+    if (journalBlocksMutation(journal)) {
+        const reason = journalBlocker(journal);
+        preview = {
+            ...preview,
+            ledgerAuthorization: "blocked",
+            ledgerDiagnostics: [...preview.ledgerDiagnostics, reason],
+            plan: blockedPlan(preview.plan, reason),
+        };
+    }
+    let outputJournal = journal;
+    let nativeResourceCleanup = preview;
+    let cleanupSummary = previewSummary(preview);
+    if (args.apply && !journalBlocksMutation(journal)) {
+        nativeResourceCleanup = applyNativeResourceCleanup(preview, {
+            ...options,
+            approved: true,
+            persistLedger(ledger) {
+                appendLifecycleOwnershipJournal(journal.path, ledger);
+            },
+        });
+        cleanupSummary = resultSummary(nativeResourceCleanup);
+        outputJournal = readLifecycleOwnershipJournal(journal.path);
+    }
+    const requiredUnmet = "plan" in nativeResourceCleanup
+        ? nativeResourceCleanup.plan.operations
+            .filter((operation) => operation.required && operation.action !== "noop")
+            .map((operation) => operation.id)
+        : nativeResourceCleanup.requiredUnmet;
+    const mode = args.apply ? "apply" : "preview";
+    return {
+        schemaVersion: LIFECYCLE_UPGRADE_SCHEMA,
+        mode,
+        status: statusFor(mode, cleanupSummary, requiredUnmet),
+        approval: args.apply ? "approved" : "not_requested",
+        platform: {
+            securePublication: secureLifecycleRemovalAvailable(),
+            requirement: "linux_proc_self_fd",
+        },
+        ownershipJournal: outputJournal,
+        nativeResourceCleanup,
+        cleanupSummary,
+        requiredUnmet,
+    };
+}