agentplane 0.3.1 → 0.3.3

package/dist/commands/upgrade/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/commands/upgrade/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,CAAC,CAAC;IAClB,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IACnC,cAAc,EAAE,wBAAwB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IACxD,WAAW,EAAE,OAAO,CAAC;IACrB,wBAAwB,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,yBAAyB,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1C,0BAA0B,EAAE,OAAO,CAAC;IACpC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EACL,MAAM,GACN,mBAAmB,GACnB,MAAM,GACN,cAAc,GACd,sBAAsB,GACtB,aAAa,GACb,iBAAiB,CAAC;CACvB,CAAC"}

package/dist/commands/upgrade/types.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/upgrade.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.command.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEnE,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC;AAEzC,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CA2JlD,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,aAAa,CACsB,CAAC"}
+{"version":3,"file":"upgrade.command.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEnE,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC;AAEzC,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CA8JlD,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,aAAa,CACsB,CAAC"}

package/dist/commands/upgrade.command.js

@@ -4,19 +4,19 @@ export const upgradeSpec = {
     id: ["upgrade"],
     group: "Setup",
     summary: "Upgrade the local agentplane framework bundle in the repo.",
-    description: "Upgrades the local agentplane framework bundle in the repo using a strict manifest of managed files. By default, upgrade generates an agent-assisted plan from the locally installed agentplane package assets (no network) and does not modify files. Use --auto to apply changes and create a dedicated upgrade commit. Use --remote to fetch a GitHub release bundle; network access is gated by config approvals.",
+    description: "Upgrades the local agentplane framework bundle in the repo using a strict manifest of managed files. By default, upgrade applies the bundled managed files from the locally installed agentplane package assets (no network) and creates a dedicated upgrade commit. Use --dry-run to preview changes without writing files, or --agent to generate a review plan instead of applying. Use --remote to fetch a GitHub release bundle; network access is gated by config approvals.",
     options: [
         {
             kind: "boolean",
             name: "agent",
             default: false,
-            description: "Generate an agent-assisted upgrade plan (no files are modified). This is the default mode.",
+            description: "Generate an agent-assisted upgrade plan instead of applying managed files.",
         },
         {
             kind: "boolean",
             name: "auto",
             default: false,
-            description: "Apply the upgrade automatically (writes managed files) and create a dedicated upgrade commit.",
+            description: "Apply the upgrade automatically (same behavior as the default mode; useful for explicit scripts).",
         },
         {
             kind: "boolean",
@@ -97,11 +97,15 @@ export const upgradeSpec = {
     examples: [
         {
             cmd: "agentplane upgrade",
-            why: "Generate an agent-assisted plan using locally installed assets (no network).",
+            why: "Apply managed files from the installed CLI assets and create an upgrade commit.",
         },
         {
-            cmd: "agentplane upgrade --auto",
-            why: "Apply the upgrade automatically (writes managed files).",
+            cmd: "agentplane upgrade --dry-run",
+            why: "Preview managed-file changes without modifying the repo.",
+        },
+        {
+            cmd: "agentplane upgrade --agent",
+            why: "Generate an agent-assisted upgrade plan instead of applying files.",
         },
         {
             cmd: "agentplane upgrade --remote --tag v0.1.9 --dry-run",
@@ -115,7 +119,7 @@ export const upgradeSpec = {
     parse: (raw) => {
         const noBackup = raw.opts["no-backup"] === true;
         return {
-            mode: raw.opts.auto === true ? "auto" : "agent",
+            mode: raw.opts.agent === true ? "agent" : "auto",
             remote: raw.opts.remote === true,
             allowTarball: raw.opts["allow-tarball"] === true,
             source: raw.opts.source,

package/dist/commands/upgrade.d.ts

@@ -12,44 +12,10 @@ export type UpgradeFlags = {
     backup: boolean;
     yes: boolean;
 };
-type GitHubRelease = {
-    tag_name?: string;
-    assets?: {
-        name?: string;
-        browser_download_url?: string;
-    }[];
-    tarball_url?: string;
-};
-export declare function normalizeFrameworkSourceForUpgrade(source: string): {
-    source: string;
-    owner: string;
-    repo: string;
-    migrated: boolean;
-};
-export declare function resolveUpgradeDownloadFromRelease(opts: {
-    release: GitHubRelease;
-    owner: string;
-    repo: string;
-    assetName: string;
-    checksumName: string;
-}): {
-    kind: "assets";
-    bundleUrl: string;
-    checksumUrl: string;
-} | {
-    kind: "tarball";
-    tarballUrl: string;
-};
-export declare function resolveRepoTarballUrl(opts: {
-    release: GitHubRelease;
-    owner: string;
-    repo: string;
-    explicitTag?: string;
-}): string;
 export declare function cmdUpgradeParsed(opts: {
     cwd: string;
     rootOverride?: string;
     flags: UpgradeFlags;
 }): Promise<number>;
-export {};
+export { normalizeFrameworkSourceForUpgrade, resolveRepoTarballUrl, resolveUpgradeDownloadFromRelease, } from "./upgrade/source.js";
 //# sourceMappingURL=upgrade.d.ts.map

package/dist/commands/upgrade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AAqCA,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAiGF,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,MAAM,GAAG;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB,CAWA;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB,GACG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAqB1C;AAUD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAgBT;AAmRD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6oBlB"}
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AA2CA,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAuMF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4gBlB;AAED,OAAO,EACL,kCAAkC,EAClC,qBAAqB,EACrB,iCAAiC,GAClC,MAAM,qBAAqB,CAAC"}

package/dist/commands/upgrade.js

@@ -1,50 +1,25 @@
-import { lstat, mkdir, mkdtemp, readdir, readFile, readlink, rm, writeFile, } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { loadConfig, resolveProject, saveConfig, setByDottedKey } from "@agentplaneorg/core";
-import { backupPath, fileExists, getPathKind } from "../cli/fs-utils.js";
+import { loadConfig, resolveProject } from "@agentplaneorg/core";
+import { fileExists, getPathKind } from "../cli/fs-utils.js";
 import { downloadToFile, fetchJson } from "../cli/http.js";
 import { parseSha256Text, sha256File } from "../cli/checksum.js";
 import { extractArchive } from "../cli/archive.js";
-import { invalidFieldMessage, invalidValueMessage, requiredFieldMessage, warnMessage, } from "../cli/output.js";
 import { exitCodeForError } from "../cli/exit-codes.js";
+import { warnMessage } from "../cli/output.js";
 import { CliError } from "../shared/errors.js";
 import { ensureNetworkApproved } from "./shared/network-approval.js";
-import { execFileAsync, gitEnv } from "./shared/git.js";
 import { getVersion } from "../meta/version.js";
+import { applyManagedFiles, cleanupAutoUpgradeArtifacts, createUpgradeCommit, ensureCleanTrackedTreeForUpgrade, persistUpgradeState, } from "./upgrade/apply.js";
+import { printUpgradeDryRun, writeUpgradeAgentReview } from "./upgrade/report.js";
+import { describeUpgradeSource, loadFrameworkManifestFromPath, normalizeFrameworkSourceForUpgrade, resolveRepoTarballUrl, resolveUpgradeDownloadFromRelease, resolveUpgradeRoot, } from "./upgrade/source.js";
 const DEFAULT_UPGRADE_ASSET = "agentplane-upgrade.tar.gz";
 const DEFAULT_UPGRADE_CHECKSUM_ASSET = "agentplane-upgrade.tar.gz.sha256";
 const UPGRADE_DOWNLOAD_TIMEOUT_MS = 60_000;
 const UPGRADE_RELEASE_METADATA_TIMEOUT_MS = 15_000;
-async function safeRemovePath(targetPath) {
-    try {
-        await rm(targetPath, { recursive: true, force: true });
-    }
-    catch {
-        // best-effort cleanup
-    }
-}
-async function cleanupAutoUpgradeArtifacts(opts) {
-    for (const backupPath of opts.createdBackups) {
-        await safeRemovePath(backupPath);
-    }
-    // Keep durable state files at .upgrade root; remove transient per-run agent artifacts.
-    await safeRemovePath(path.join(opts.upgradeStateDir, "agent"));
-}
 const ASSETS_DIR_URL = new URL("../../assets/", import.meta.url);
-async function loadFrameworkManifestFromPath(manifestPath) {
-    const text = await readFile(manifestPath, "utf8");
-    const parsed = JSON.parse(text);
-    if (parsed?.schema_version !== 1 || !Array.isArray(parsed?.files)) {
-        throw new CliError({
-            exitCode: 3,
-            code: "E_VALIDATION",
-            message: "Invalid framework.manifest.json (expected schema_version=1 and files array).",
-        });
-    }
-    return parsed;
-}
 function isDeniedUpgradePath(relPath) {
     if (relPath === ".agentplane/config.json")
         return true;
@@ -64,89 +39,6 @@ function isDeniedUpgradePath(relPath) {
         return true;
     return false;
 }
-function parseGitHubRepo(source) {
-    const trimmed = source.trim();
-    if (!trimmed)
-        throw new Error(requiredFieldMessage("config.framework.source"));
-    if (!trimmed.includes("github.com")) {
-        throw new Error(invalidFieldMessage("config.framework.source", "GitHub URL"));
-    }
-    try {
-        const url = new URL(trimmed);
-        const parts = url.pathname.replaceAll(".git", "").split("/").filter(Boolean);
-        if (parts.length < 2)
-            throw new Error(invalidValueMessage("GitHub repo URL", trimmed, "owner/repo"));
-        return { owner: parts[0], repo: parts[1] };
-    }
-    catch {
-        throw new Error(invalidValueMessage("GitHub repo URL", trimmed, "owner/repo"));
-    }
-}
-export function normalizeFrameworkSourceForUpgrade(source) {
-    const { owner, repo } = parseGitHubRepo(source);
-    if (owner === "basilisk-labs" && repo === "agent-plane") {
-        return {
-            source: `https://github.com/${owner}/agentplane`,
-            owner,
-            repo: "agentplane",
-            migrated: true,
-        };
-    }
-    return { source: `https://github.com/${owner}/${repo}`, owner, repo, migrated: false };
-}
-export function resolveUpgradeDownloadFromRelease(opts) {
-    const assets = Array.isArray(opts.release.assets) ? opts.release.assets : [];
-    const asset = assets.find((a) => a?.name === opts.assetName);
-    const checksumAsset = assets.find((a) => a?.name === opts.checksumName);
-    if (asset?.browser_download_url && checksumAsset?.browser_download_url) {
-        return {
-            kind: "assets",
-            bundleUrl: asset.browser_download_url,
-            checksumUrl: checksumAsset.browser_download_url,
-        };
-    }
-    const tarballUrl = typeof opts.release.tarball_url === "string" ? opts.release.tarball_url : "";
-    if (!tarballUrl) {
-        throw new CliError({
-            exitCode: exitCodeForError("E_NETWORK"),
-            code: "E_NETWORK",
-            message: `Upgrade assets not found in ${opts.owner}/${opts.repo} release`,
-        });
-    }
-    return { kind: "tarball", tarballUrl };
-}
-function buildCodeloadTarGzUrl(opts) {
-    // Prefer codeload over api.github.com tarball_url. It is less brittle and does not require
-    // GitHub API-specific behavior/rate limits.
-    const tag = opts.tag.trim();
-    if (!tag)
-        throw new Error("tag is required");
-    return `https://codeload.github.com/${opts.owner}/${opts.repo}/tar.gz/${encodeURIComponent(tag)}`;
-}
-export function resolveRepoTarballUrl(opts) {
-    const tag = (typeof opts.explicitTag === "string" && opts.explicitTag.trim()) ||
-        (typeof opts.release.tag_name === "string" && opts.release.tag_name.trim()) ||
-        "";
-    if (tag)
-        return buildCodeloadTarGzUrl({ owner: opts.owner, repo: opts.repo, tag });
-    const tarballUrl = typeof opts.release.tarball_url === "string" ? opts.release.tarball_url : "";
-    if (tarballUrl)
-        return tarballUrl;
-    throw new CliError({
-        exitCode: exitCodeForError("E_NETWORK"),
-        code: "E_NETWORK",
-        message: "GitHub release did not provide tag_name or tarball_url; cannot fall back to repo tarball.",
-    });
-}
-async function resolveUpgradeRoot(extractedDir) {
-    const entries = await readdir(extractedDir, { withFileTypes: true });
-    const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-    const files = entries.filter((entry) => entry.isFile()).map((entry) => entry.name);
-    if (files.length === 0 && dirs.length === 1) {
-        return path.join(extractedDir, dirs[0]);
-    }
-    return extractedDir;
-}
 function isAllowedUpgradePath(relPath) {
     if (relPath === "AGENTS.md")
         return true;
@@ -297,73 +189,9 @@ function normalizeUpgradeVersionLabel(input) {
         return trimmed;
     return `v${trimmed}`;
 }
-async function ensureCleanTrackedTreeForUpgrade(gitRoot) {
-    const { stdout } = await execFileAsync("git", ["status", "--short", "--untracked-files=no"], {
-        cwd: gitRoot,
-        env: gitEnv(),
-        maxBuffer: 10 * 1024 * 1024,
-    });
-    const dirty = String(stdout ?? "")
-        .split(/\r?\n/u)
-        .map((line) => line.trimEnd())
-        .filter((line) => line.length > 0);
-    if (dirty.length === 0)
-        return;
-    throw new CliError({
-        exitCode: exitCodeForError("E_GIT"),
-        code: "E_GIT",
-        message: "Upgrade --auto requires a clean tracked working tree.\n" +
-            `Found tracked changes:\n${dirty.map((line) => `  ${line}`).join("\n")}`,
-    });
-}
-async function createUpgradeCommit(opts) {
-    const uniquePaths = [...new Set(opts.paths.filter(Boolean))];
-    if (uniquePaths.length === 0)
-        return null;
-    await execFileAsync("git", ["add", "--", ...uniquePaths], {
-        cwd: opts.gitRoot,
-        env: gitEnv(),
-        maxBuffer: 10 * 1024 * 1024,
-    });
-    const { stdout: stagedOut } = await execFileAsync("git", ["diff", "--cached", "--name-only", "-z"], {
-        cwd: opts.gitRoot,
-        env: gitEnv(),
-        encoding: "buffer",
-        maxBuffer: 10 * 1024 * 1024,
-    });
-    const staged = (Buffer.isBuffer(stagedOut) ? stagedOut.toString("utf8") : String(stagedOut ?? ""))
-        .split("\0")
-        .map((entry) => entry.trim())
-        .some(Boolean);
-    if (!staged)
-        return null;
-    const subject = `⬆️ upgrade: apply framework ${opts.versionLabel}`;
-    const body = `Upgrade-Version: ${opts.versionLabel}\n` +
-        `Source: ${opts.source}\n` +
-        `Managed-Changes: add=${opts.additions}, update=${opts.updates}, unchanged=${opts.unchanged}\n` +
-        `Incidents-Appended: ${opts.incidentsAppendedCount}\n`;
-    try {
-        await execFileAsync("git", ["commit", "-m", subject, "-m", body], {
-            cwd: opts.gitRoot,
-            env: gitEnv(),
-            maxBuffer: 10 * 1024 * 1024,
-        });
-    }
-    catch (err) {
-        const details = err?.stderr ?? "";
-        throw new CliError({
-            exitCode: exitCodeForError("E_GIT"),
-            code: "E_GIT",
-            message: "Upgrade applied but failed to create the upgrade commit.\n" +
-                "Fix commit policy/hook issues and commit the staged upgrade files as a dedicated upgrade commit.\n" +
-                (String(details).trim() ? `Details:\n${String(details).trim()}` : ""),
-        });
-    }
-    const { stdout: hashOut } = await execFileAsync("git", ["rev-parse", "HEAD"], {
-        cwd: opts.gitRoot,
-        env: gitEnv(),
-    });
-    return { hash: String(hashOut ?? "").trim(), subject };
+function normalizeVersionForConfig(input) {
+    const trimmed = input.trim().replace(/^v/i, "");
+    return trimmed.length > 0 ? trimmed : null;
 }
 export async function cmdUpgradeParsed(opts) {
     const flags = opts.flags;
@@ -537,6 +365,14 @@ export async function cmdUpgradeParsed(opts) {
             ? fileURLToPath(new URL("../../assets/framework.manifest.json", import.meta.url))
             : path.join(bundleRoot, "framework.manifest.json");
         const manifest = await loadFrameworkManifestFromPath(manifestPath);
+        const modeLabel = flags.dryRun ? "dry-run" : flags.mode === "agent" ? "review" : "apply";
+        process.stdout.write(`Upgrade source: ${describeUpgradeSource({
+            bundleLayout,
+            hasExplicitBundle: hasBundle,
+            useRemote,
+        })}\n` +
+            `Upgrade version: ${upgradeVersionLabel}\n` +
+            `Upgrade mode: ${modeLabel}\n`);
         const additions = [];
         const updates = [];
         const skipped = [];
@@ -752,15 +588,7 @@ export async function cmdUpgradeParsed(opts) {
             });
         }
         if (flags.dryRun) {
-            process.stdout.write(`Upgrade dry-run: ${additions.length} add, ${updates.length} update, ${skipped.length} unchanged\n`);
-            for (const rel of additions)
-                process.stdout.write(`ADD ${rel}\n`);
-            for (const rel of updates)
-                process.stdout.write(`UPDATE ${rel}\n`);
-            for (const rel of skipped)
-                process.stdout.write(`SKIP ${rel}\n`);
-            for (const rel of merged)
-                process.stdout.write(`MERGE ${rel}\n`);
+            printUpgradeDryRun({ additions, updates, skipped, merged });
             return 0;
         }
         const needsReview = reviewRecords.filter((r) => r.needsSemanticReview);
@@ -771,140 +599,45 @@ export async function cmdUpgradeParsed(opts) {
                 process.stdout.write("Upgrade plan: no managed changes detected\n");
                 return 0;
             }
-            const agentDir = path.join(upgradeStateDir, "agent");
-            const runId = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
-            const runDir = path.join(agentDir, runId);
-            await mkdir(runDir, { recursive: true });
-            const managedFiles = manifest.files.map((f) => f.path.replaceAll("\\", "/").trim());
-            const planMd = `# agentplane upgrade plan (${runId})\n\n` +
-                `Mode: agent-assisted (no files modified)\n\n` +
-                `## Summary\n\n` +
-                `- additions: ${additions.length}\n` +
-                `- updates: ${updates.length}\n` +
-                `- unchanged: ${skipped.length}\n` +
-                `- merged (auto-safe transforms already applied to incoming): ${merged.length}\n\n` +
-                `## Managed files (manifest)\n\n` +
-                managedFiles.map((p) => `- ${p}`).join("\n") +
-                `\n\n` +
-                `## Proposed changes\n\n` +
-                additions.map((p) => `- ADD ${p}`).join("\n") +
-                (additions.length > 0 ? "\n" : "") +
-                updates.map((p) => `- UPDATE ${p}`).join("\n") +
-                (updates.length > 0 ? "\n" : "") +
-                merged.map((p) => `- MERGE ${p}`).join("\n") +
-                (merged.length > 0 ? "\n" : "") +
-                skipped.map((p) => `- SKIP ${p}`).join("\n") +
-                (skipped.length > 0 ? "\n" : "") +
-                `\n` +
-                `## Next steps\n\n` +
-                `1. Review the proposed changes list.\n` +
-                `2. Apply changes manually or re-run with \`agentplane upgrade --auto\` to apply managed files.\n` +
-                `3. Run \`agentplane doctor\` (or \`agentplane doctor --fix\`) and ensure checks pass.\n`;
-            const constraintsMd = `# Upgrade constraints\n\n` +
-                `This upgrade is restricted to framework-managed files only.\n\n` +
-                `## Must not touch\n\n` +
-                `- .agentplane/tasks/** (task data)\n` +
-                `- .agentplane/tasks.json (export snapshot)\n` +
-                `- .agentplane/backends/** (backend configuration)\n` +
-                `- .agentplane/config.json (project config)\n` +
-                `- .git/**\n\n` +
-                `## Notes\n\n` +
-                `- The upgrade bundle is validated against framework.manifest.json.\n` +
-                `- The policy gateway file at workspace root is AGENTS.md or CLAUDE.md.\n`;
-            const reportMd = `# Upgrade report (${runId})\n\n` +
-                `## Actions taken\n\n` +
-                `- [ ] Reviewed plan.md\n` +
-                `- [ ] Applied changes (manual or --auto)\n` +
-                `- [ ] Ran doctor\n` +
-                `- [ ] Ran tests / lint\n\n` +
-                `## Notes\n\n` +
-                `- \n`;
-            await writeFile(path.join(runDir, "plan.md"), planMd, "utf8");
-            await writeFile(path.join(runDir, "constraints.md"), constraintsMd, "utf8");
-            await writeFile(path.join(runDir, "report.md"), reportMd, "utf8");
-            await writeFile(path.join(runDir, "files.json"), JSON.stringify({ additions, updates, skipped, merged }, null, 2) + "\n", "utf8");
-            await writeFile(path.join(runDir, "review.json"), JSON.stringify({
-                generated_at: new Date().toISOString(),
-                counts: {
-                    total: reviewRecords.length,
-                    needsSemanticReview: needsReview.length,
-                },
-                files: reviewRecords,
-            }, null, 2) + "\n", "utf8");
-            const relRunDir = path.relative(resolved.gitRoot, runDir);
+            const { relRunDir, needsReviewCount } = await writeUpgradeAgentReview({
+                gitRoot: resolved.gitRoot,
+                runRoot: path.join(upgradeStateDir, "agent"),
+                manifest,
+                additions,
+                updates,
+                skipped,
+                merged,
+                reviewRecords,
+            });
             process.stdout.write(`Upgrade plan written: ${relRunDir}\n`);
-            process.stdout.write(`Review-required files: ${needsReview.length}\n`);
+            process.stdout.write(`Review-required files: ${needsReviewCount}\n`);
             return 0;
         }
-        for (const rel of [...additions, ...updates]) {
-            const destPath = path.join(resolved.gitRoot, rel);
-            if (flags.backup && (await fileExists(destPath))) {
-                const backup = await backupPath(destPath);
-                createdBackups.push(backup);
-            }
-            await mkdir(path.dirname(destPath), { recursive: true });
-            const data = fileContents.get(rel);
-            if (data) {
-                if (rel === "AGENTS.md" || rel === "CLAUDE.md") {
-                    // If policy gateway file is a symlink, avoid overwriting an arbitrary external target.
-                    // This permits repo-internal symlinks (e.g. the agentplane repo itself) while
-                    // keeping user workspaces safe.
-                    try {
-                        const st = await lstat(destPath);
-                        if (st.isSymbolicLink()) {
-                            const linkTarget = await readlink(destPath);
-                            const targetAbs = path.resolve(path.dirname(destPath), linkTarget);
-                            const relFromRoot = path.relative(resolved.gitRoot, targetAbs);
-                            if (relFromRoot.startsWith("..") || path.isAbsolute(relFromRoot)) {
-                                throw new CliError({
-                                    exitCode: exitCodeForError("E_VALIDATION"),
-                                    code: "E_VALIDATION",
-                                    message: `Refusing to overwrite symlinked ${rel} target outside repo: ${linkTarget}. ` +
-                                        "Replace the symlink with a regular file and retry.",
-                                });
-                            }
-                        }
-                    }
-                    catch (err) {
-                        const code = err?.code;
-                        if (code !== "ENOENT")
-                            throw err;
-                    }
-                }
-                await writeFile(destPath, data);
-            }
-            // Record a baseline copy for future three-way merges.
-            const baselineKey = toBaselineKey(rel);
-            if (baselineKey && data) {
-                const baselinePath = path.join(baselineDirNew, baselineKey);
-                await mkdir(path.dirname(baselinePath), { recursive: true });
-                await writeFile(baselinePath, data);
-            }
-        }
+        await applyManagedFiles({
+            gitRoot: resolved.gitRoot,
+            additions,
+            updates,
+            backup: flags.backup,
+            fileContents,
+            baselineDir: baselineDirNew,
+            createdBackups,
+            toBaselineKey,
+        });
         const hasManagedMutations = additions.length > 0 || updates.length > 0;
-        const hasSourceMigration = normalizedSourceToPersist !== null;
-        const shouldMutateConfig = hasManagedMutations || hasSourceMigration;
-        if (shouldMutateConfig) {
-            const raw = { ...loaded.raw };
-            if (normalizedSourceToPersist) {
-                setByDottedKey(raw, "framework.source", normalizedSourceToPersist);
-            }
-            setByDottedKey(raw, "framework.last_update", new Date().toISOString());
-            await saveConfig(resolved.agentplaneDir, raw);
-        }
-        await writeFile(statePath, JSON.stringify({
-            applied_at: new Date().toISOString(),
+        const shouldMutateConfig = await persistUpgradeState({
+            agentplaneDir: resolved.agentplaneDir,
+            rawConfig: loaded.raw,
+            normalizedSourceToPersist,
+            expectedCliVersionToPersist: normalizeVersionForConfig(upgradeVersionLabel),
+            hasManagedMutations,
+            statePath,
+            upgradeStateDir,
             source: bundleLayout,
-            updated: { add: additions.length, update: updates.length, unchanged: skipped.length },
-        }, null, 2) + "\n", "utf8");
-        await writeFile(path.join(upgradeStateDir, "last-review.json"), JSON.stringify({
-            generated_at: new Date().toISOString(),
-            counts: {
-                total: reviewRecords.length,
-                needsSemanticReview: reviewRecords.filter((r) => r.needsSemanticReview).length,
-            },
-            files: reviewRecords,
-        }, null, 2) + "\n", "utf8");
+            reviewRecords,
+            additions: additions.length,
+            updates: updates.length,
+            skipped: skipped.length,
+        });
         const commitPaths = [
             ...new Set([...additions, ...updates, ...(shouldMutateConfig ? [CONFIG_REL_PATH] : [])]),
         ];
@@ -940,3 +673,4 @@ export async function cmdUpgradeParsed(opts) {
         }
     }
 }
+export { normalizeFrameworkSourceForUpgrade, resolveRepoTarballUrl, resolveUpgradeDownloadFromRelease, } from "./upgrade/source.js";

package/dist/shared/diagnostics.d.ts

@@ -0,0 +1,23 @@
+export type DiagnosticNextAction = {
+    command: string;
+    reason: string;
+    reasonCode?: string;
+};
+export type DiagnosticInfo = {
+    state: string;
+    likelyCause: string;
+    nextAction?: DiagnosticNextAction;
+    hint?: string;
+};
+type DiagnosticContextRecord = Record<string, unknown>;
+export declare function withDiagnosticContext(context: DiagnosticContextRecord | undefined, diagnostic: DiagnosticInfo): DiagnosticContextRecord;
+export declare function readDiagnosticContext(context: DiagnosticContextRecord | undefined): Partial<DiagnosticInfo>;
+export declare function renderDiagnosticFinding(opts: {
+    severity: "ERROR" | "WARN" | "INFO";
+    state: string;
+    likelyCause: string;
+    nextAction?: DiagnosticNextAction;
+    details?: string[];
+}): string;
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/shared/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/shared/diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAMvD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,uBAAuB,GAAG,SAAS,EAC5C,UAAU,EAAE,cAAc,GACzB,uBAAuB,CAiBzB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,uBAAuB,GAAG,SAAS,GAC3C,OAAO,CAAC,cAAc,CAAC,CAqBzB;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,GAAG,MAAM,CAaT"}

package/dist/shared/diagnostics.js

@@ -0,0 +1,57 @@
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+export function withDiagnosticContext(context, diagnostic) {
+    const base = context ? { ...context } : {};
+    return {
+        ...base,
+        diagnostic_state: diagnostic.state,
+        diagnostic_likely_cause: diagnostic.likelyCause,
+        ...(diagnostic.hint ? { diagnostic_hint: diagnostic.hint } : {}),
+        ...(diagnostic.nextAction
+            ? {
+                diagnostic_next_action_command: diagnostic.nextAction.command,
+                diagnostic_next_action_reason: diagnostic.nextAction.reason,
+                ...(diagnostic.nextAction.reasonCode
+                    ? { diagnostic_next_action_reason_code: diagnostic.nextAction.reasonCode }
+                    : {}),
+            }
+            : {}),
+    };
+}
+export function readDiagnosticContext(context) {
+    const state = readString(context?.diagnostic_state);
+    const likelyCause = readString(context?.diagnostic_likely_cause);
+    const hint = readString(context?.diagnostic_hint);
+    const nextActionCommand = readString(context?.diagnostic_next_action_command);
+    const nextActionReason = readString(context?.diagnostic_next_action_reason);
+    const nextActionReasonCode = readString(context?.diagnostic_next_action_reason_code);
+    return {
+        state,
+        likelyCause,
+        hint,
+        nextAction: nextActionCommand && nextActionReason
+            ? {
+                command: nextActionCommand,
+                reason: nextActionReason,
+                ...(nextActionReasonCode ? { reasonCode: nextActionReasonCode } : {}),
+            }
+            : undefined,
+    };
+}
+export function renderDiagnosticFinding(opts) {
+    const lines = [`[${opts.severity}] State: ${opts.state}`, `Likely cause: ${opts.likelyCause}`];
+    if (opts.nextAction) {
+        lines.push(`Next action: ${opts.nextAction.command} (${opts.nextAction.reason})`);
+    }
+    if (Array.isArray(opts.details) && opts.details.length > 0) {
+        const [first, ...rest] = opts.details;
+        if (first)
+            lines.push(`Details: ${first}`);
+        for (const detail of rest) {
+            if (detail.trim())
+                lines.push(`  - ${detail}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/shared/errors.d.ts

@@ -11,6 +11,8 @@ export declare class CliError extends Error {
     });
 }
 export type JsonErrorGuidance = {
+    state?: string;
+    likelyCause?: string;
     hint?: string;
     nextAction?: {
         command: string;