@goodandready/dsh-approval-gate 0.1.19 → 0.1.21

package/lib/messages.js

@@ -22,6 +22,7 @@ export const MESSAGES = Object.freeze({
     detailUnsupported: "unsupported shell syntax",
     approvalRequired: "Approval required",
     askUnknown: "The command could not be fully inspected; review it before allowing",
+    askUnmatched: "The operation was not recognized by safety rules; human confirmation is required by default",
     askUnparseable: "Shell syntax could not be fully inspected; review it before allowing",
     askUnknownFormat: "The tool call format could not be inspected; review it before allowing",
     askUnknownWriteTarget: "The file write target could not be identified; review it before allowing",
@@ -77,6 +78,10 @@ export const MESSAGES = Object.freeze({
     ruleUnisolatedTempPath: "Target path uses unisolated global temp directory",
     askOverengineeringLimit: "Session file creation limit exceeded; potential overengineering requires review before allowing",
     ruleOverengineeringLimit: "Session exceeded maximum allowed created files limit",
+    ruleAgentsMdProhibitedCommand: "Command execution prohibited by rules in AGENTS.md",
+    ruleAgentsMdProhibitedPath: "File modification prohibited by rules in AGENTS.md",
+    askMajorVersionBump: "Package.json modification contains major dependency bump; review before allowing",
+    ruleMajorVersionBump: "Unauthorized major dependency version bump",
     hintRecursiveRm: "Specify exact target files instead of recursive deletion",
     hintPathTraversal: "Keep operations strictly within the project directory",
     hintSecretWrite: "Modify configuration via settings or environment variables, not raw file overwrite",
@@ -100,6 +105,10 @@ export const MESSAGES = Object.freeze({
     hintContractViolation: "Confine operations to permitted task tools and project scope",
     hintUnisolatedTempPath: "Use workspace-isolated temporary directory (<workspace>/.dsh/tmp)",
     hintOverengineeringLimit: "Reuse existing files and avoid creating redundant abstractions or boilerplate",
+    hintTrashAlternative: "Move files to reversible .dsh/trash/<session>/ directory instead of rm",
+    hintAgentsMdProhibited: "Review project-specific guidelines and constraints defined in AGENTS.md",
+    hintMajorVersionBump: "Verify compatibility before bumping major dependency versions in package.json",
+    hintUnmatchedAsk: "Unrecognized operations default to fail-closed approval under defaultVerdict='ask'",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
@@ -121,6 +130,7 @@ export const MESSAGES = Object.freeze({
     detailUnsupported: "不支持的 shell 语法",
     approvalRequired: "需要批准",
     askUnknown: "命令无法完整检查；请在允许前进行审查",
+    askUnmatched: "该操作未被安全规则识别；默认需要人工确认",
     askUnparseable: "Shell 语法无法完整检查；请在允许前进行审查",
     askUnknownFormat: "工具调用格式无法检查；请在允许前进行审查",
     askUnknownWriteTarget: "无法识别文件写入目标；请在允许前进行审查",
@@ -176,6 +186,10 @@ export const MESSAGES = Object.freeze({
     ruleUnisolatedTempPath: "目标路径使用未隔离的全局临时目录",
     askOverengineeringLimit: "会话创建文件数超过限制；潜在的过度工程需要人工审查",
     ruleOverengineeringLimit: "会话超出最大允许创建文件数限制",
+    ruleAgentsMdProhibitedCommand: "命令执行被 AGENTS.md 中的规则明确禁止",
+    ruleAgentsMdProhibitedPath: "文件修改被 AGENTS.md 中的规则明确禁止",
+    askMajorVersionBump: "package.json 包含破坏性依赖主版本升级；请在允许前进行审查",
+    ruleMajorVersionBump: "未授权的依赖包主版本升级",
     hintRecursiveRm: "请指定具体目标文件，避免递归删除",
     hintPathTraversal: "请将操作限制在项目根目录内",
     hintSecretWrite: "请通过设置或环境变量修改配置，不要直接覆盖敏感配置文件",
@@ -199,6 +213,10 @@ export const MESSAGES = Object.freeze({
     hintContractViolation: "将操作限制在允许的任务工具和项目范围内",
     hintUnisolatedTempPath: "使用工作区隔离的临时目录 (<workspace>/.dsh/tmp)",
     hintOverengineeringLimit: "复用现有文件，避免创建多余的抽象或样板代码",
+    hintTrashAlternative: "建议将文件移动到可逆的 .dsh/trash/<session>/ 目录，避免直接 rm",
+    hintAgentsMdProhibited: "请核对项目根目录 AGENTS.md 中定义的安全约束和禁止指令",
+    hintMajorVersionBump: "在升级 package.json 依赖主版本前请确认破坏性变更与兼容性",
+    hintUnmatchedAsk: "在 defaultVerdict='ask' 模式下，未识别的操作默认需要人工审核确认",
   },
 });
 
@@ -270,10 +288,13 @@ const RULE_KEYS = Object.freeze({
   "contract-violation": "ruleContractViolation",
   "unisolated-temp-path": "ruleUnisolatedTempPath",
   "overengineering-file-limit": "ruleOverengineeringLimit",
+  "agents-md-prohibited-command": "ruleAgentsMdProhibitedCommand",
+  "agents-md-prohibited-path": "ruleAgentsMdProhibitedPath",
+  "major-version-bump": "askMajorVersionBump",
 });
 
 const HINT_KEYS = Object.freeze({
-  "recursive-rm": "hintRecursiveRm",
+  "recursive-rm": "hintTrashAlternative",
   "path-traversal": "hintPathTraversal",
   "secret-write": "hintSecretWrite",
   "env-dump-leak": "hintEnvDumpLeak",
@@ -297,12 +318,17 @@ const HINT_KEYS = Object.freeze({
   "contract-violation": "hintContractViolation",
   "unisolated-temp-path": "hintUnisolatedTempPath",
   "overengineering-file-limit": "hintOverengineeringLimit",
+  "agents-md-prohibited-command": "hintAgentsMdProhibited",
+  "agents-md-prohibited-path": "hintAgentsMdProhibited",
+  "major-version-bump": "hintMajorVersionBump",
+  "unmatched-ask": "hintUnmatchedAsk",
 });
 
 const ASK_KEYS = Object.freeze({
   unparseable: "askUnparseable",
   "unknown-format": "askUnknownFormat",
   "unknown-write-target": "askUnknownWriteTarget",
+  "unmatched-ask": "askUnmatched",
   "dynamic-command": "askDynamicCommand",
   "dynamic-arguments": "askDynamicArguments",
   "dynamic-redirect": "askDynamicRedirect",
@@ -321,6 +347,7 @@ const ASK_KEYS = Object.freeze({
   "contract-violation": "askContractViolation",
   "unisolated-temp-path": "askUnisolatedTempPath",
   "overengineering-file-limit": "askOverengineeringLimit",
+  "major-version-bump": "askMajorVersionBump",
 });
 
 const DETAIL_KEYS = Object.freeze({

package/lib/snapshots.js

@@ -0,0 +1,268 @@
+// lib/snapshots.js
+// Pre-execution Snapshots (#77), Undo/Rollback (#76), and Dual-level Cleanup (#78).
+// Zero external dependencies; safe filesystem operations with in-memory metadata.
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+export const DEFAULT_MAX_SNAPSHOTS_PER_SESSION = 50;
+export const DEFAULT_MAX_SNAPSHOT_BYTES = 1024 * 1024; // 1 MB
+
+export class SnapshotManager {
+  /**
+   * @param {Record<string, any>} [options]
+   */
+  constructor(options = {}) {
+    this.maxSnapshotsPerSession = Number(options.maxSnapshotsPerSession) || DEFAULT_MAX_SNAPSHOTS_PER_SESSION;
+    this.maxSnapshotBytes = Number(options.maxSnapshotBytes) || DEFAULT_MAX_SNAPSHOT_BYTES;
+    this.workspaceDir = options.workspaceDir ? path.resolve(options.workspaceDir) : "";
+
+    /** @type {Map<string, Record<string, any>>} snapshotId -> Snapshot */
+    this.snapshots = new Map();
+    /** @type {Map<string, string[]>} sessionId -> [snapshotId, ...] */
+    this.sessionIndex = new Map();
+    /** @type {Map<string, string>} callId -> snapshotId */
+    this.callIndex = new Map();
+  }
+
+  /**
+   * Resolves absolute file path within workspace or host.
+   * @param {string} targetPath
+   * @returns {string}
+   */
+  resolvePath(targetPath) {
+    if (!targetPath || typeof targetPath !== "string") return "";
+    if (path.isAbsolute(targetPath)) return path.normalize(targetPath);
+    if (this.workspaceDir) return path.resolve(this.workspaceDir, targetPath);
+    return path.resolve(targetPath);
+  }
+
+  /**
+   * Captures a pre-execution snapshot before file mutation (#77).
+   * @param {string} targetPath - Relative or absolute path to target file
+   * @param {Record<string, any>} [meta] - Metadata (sessionId, callId, tool)
+   * @returns {Record<string, any>} Created snapshot record
+   */
+  takeSnapshot(targetPath, meta = {}) {
+    const resolved = this.resolvePath(targetPath);
+    if (!resolved) {
+      return { success: false, error: "invalid-target-path" };
+    }
+
+    const sessionId = String(meta.sessionId || "default");
+    const callId = meta.callId ? String(meta.callId) : null;
+    const tool = meta.tool ? String(meta.tool) : "unknown";
+
+    let existed = false;
+    let content = null;
+    let tooLarge = false;
+    let size = 0;
+
+    try {
+      if (fs.existsSync(resolved)) {
+        existed = true;
+        const stat = fs.statSync(resolved);
+        size = stat.size;
+        if (size > this.maxSnapshotBytes) {
+          tooLarge = true;
+        } else {
+          content = fs.readFileSync(resolved, "utf8");
+        }
+      }
+    } catch {
+      // If file unreadable or permission error, proceed safely
+      existed = false;
+    }
+
+    const id = "snap_" + Date.now() + "_" + crypto.randomBytes(4).toString("hex");
+    const snapshot = {
+      id,
+      sessionId,
+      callId,
+      tool,
+      targetPath: resolved,
+      originalPath: targetPath,
+      existed,
+      content,
+      size,
+      tooLarge,
+      createdAt: Date.now(),
+      rolledBack: false,
+      rolledBackAt: null,
+    };
+
+    this.snapshots.set(id, snapshot);
+
+    if (callId) {
+      this.callIndex.set(callId, id);
+    }
+
+    if (!this.sessionIndex.has(sessionId)) {
+      this.sessionIndex.set(sessionId, []);
+    }
+    const sessionList = this.sessionIndex.get(sessionId);
+    sessionList.push(id);
+
+    // Evict oldest if exceeding maxSnapshotsPerSession
+    if (sessionList.length > this.maxSnapshotsPerSession) {
+      const evictedId = sessionList.shift();
+      if (evictedId) {
+        const evicted = this.snapshots.get(evictedId);
+        if (evicted && evicted.callId) {
+          this.callIndex.delete(evicted.callId);
+        }
+        this.snapshots.delete(evictedId);
+      }
+    }
+
+    return snapshot;
+  }
+
+  /**
+   * Retrieves a snapshot by ID.
+   * @param {string} id
+   * @returns {Record<string, any> | null}
+   */
+  getSnapshot(id) {
+    return this.snapshots.get(id) || null;
+  }
+
+  /**
+   * Retrieves a snapshot by tool callId.
+   * @param {string} callId
+   * @returns {Record<string, any> | null}
+   */
+  getSnapshotByCallId(callId) {
+    const id = this.callIndex.get(String(callId));
+    return id ? this.getSnapshot(id) : null;
+  }
+
+  /**
+   * Retrieves all snapshots for a session.
+   * @param {string} sessionId
+   * @returns {Record<string, any>[]}
+   */
+  getSnapshots(sessionId) {
+    const ids = this.sessionIndex.get(String(sessionId)) || [];
+    const res = [];
+    for (const id of ids) {
+      const snap = this.snapshots.get(id);
+      if (snap) res.push(snap);
+    }
+    return res;
+  }
+
+  /**
+   * Undoes a file change by rolling back to its pre-execution snapshot (#76).
+   * @param {string} snapshotIdOrCallback - Snapshot ID or Call ID
+   * @returns {{ success: boolean, error?: string, snapshotId?: string, targetPath?: string, restoredExisted?: boolean }}
+   */
+  rollbackSnapshot(snapshotIdOrCallback) {
+    if (!snapshotIdOrCallback) {
+      return { success: false, error: "snapshot-id-required" };
+    }
+
+    let snap = this.snapshots.get(snapshotIdOrCallback);
+    if (!snap) {
+      const id = this.callIndex.get(String(snapshotIdOrCallback));
+      if (id) snap = this.snapshots.get(id);
+    }
+
+    if (!snap) {
+      return { success: false, error: "snapshot-not-found" };
+    }
+
+    if (snap.rolledBack) {
+      return { success: false, error: "snapshot-already-rolled-back", snapshotId: snap.id };
+    }
+
+    if (snap.tooLarge) {
+      return { success: false, error: "snapshot-size-limit-exceeded", snapshotId: snap.id };
+    }
+
+    try {
+      if (snap.existed && snap.content !== null) {
+        // Restore previous content
+        const dir = path.dirname(snap.targetPath);
+        if (!fs.existsSync(dir)) {
+          fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(snap.targetPath, snap.content, "utf8");
+      } else if (!snap.existed) {
+        // File was newly created by this call: delete it to undo
+        if (fs.existsSync(snap.targetPath)) {
+          fs.unlinkSync(snap.targetPath);
+        }
+      }
+
+      snap.rolledBack = true;
+      snap.rolledBackAt = Date.now();
+
+      return {
+        success: true,
+        snapshotId: snap.id,
+        targetPath: snap.targetPath,
+        restoredExisted: snap.existed,
+        rolledBackAt: snap.rolledBackAt,
+      };
+    } catch (err) {
+      return {
+        success: false,
+        error: "rollback-io-error",
+        detail: String(err && err.message || err),
+        snapshotId: snap.id,
+      };
+    }
+  }
+
+  /**
+   * Cleans up snapshots for a single session safely (#78).
+   * @param {string} sessionId
+   * @returns {{ cleared: number, sessionId: string }}
+   */
+  clearSnapshots(sessionId) {
+    const sId = String(sessionId || "default");
+    const ids = this.sessionIndex.get(sId) || [];
+    let cleared = 0;
+    for (const id of ids) {
+      const snap = this.snapshots.get(id);
+      if (snap && snap.callId) {
+        this.callIndex.delete(snap.callId);
+      }
+      if (this.snapshots.delete(id)) {
+        cleared++;
+      }
+    }
+    this.sessionIndex.delete(sId);
+    return { cleared, sessionId: sId };
+  }
+
+  /**
+   * Cleans up snapshots globally across all sessions (#78).
+   * @returns {{ cleared: number }}
+   */
+  clearAllSnapshots() {
+    const total = this.snapshots.size;
+    this.snapshots.clear();
+    this.sessionIndex.clear();
+    this.callIndex.clear();
+    return { cleared: total };
+  }
+
+  /**
+   * Returns snapshot usage metrics and statistics.
+   * @returns {{ totalSnapshots: number, sessionCount: number, totalBytes: number }}
+   */
+  getStats() {
+    let totalBytes = 0;
+    for (const snap of this.snapshots.values()) {
+      totalBytes += snap.size || 0;
+    }
+    return {
+      totalSnapshots: this.snapshots.size,
+      sessionCount: this.sessionIndex.size,
+      totalBytes,
+    };
+  }
+}

package/lib/trash.js

@@ -0,0 +1,119 @@
+// lib/trash.js
+// Reversible Trash Move: safe alternative to destructive rm commands (#104).
+
+import path from "node:path";
+
+const RM_COMMAND_PATTERN = /^\s*rm\b/i;
+const RM_FLAGS_PATTERN = /^-[a-zA-Z0-9_\-]+$/;
+
+/**
+ * Resolves the isolated trash directory for a workspace and session (#104).
+ * Default path: <workspaceDir>/.dsh/trash/<sessionId>
+ *
+ * @param {string} [workspaceDir]
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function resolveTrashDir(workspaceDir, sessionId = "default") {
+  const base = workspaceDir && typeof workspaceDir === "string" ? workspaceDir : ".";
+  const session = String(sessionId || "default").replace(/[^a-zA-Z0-9_\-]/g, "_");
+  return path.join(base, ".dsh", "trash", session);
+}
+
+/**
+ * Checks if a shell command is an rm command (#104).
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function isRmCommand(command) {
+  if (typeof command !== "string") return false;
+  return RM_COMMAND_PATTERN.test(command.trim());
+}
+
+/**
+ * Extracts target file and directory paths from an rm command string (#104).
+ *
+ * @param {string} command
+ * @returns {string[]}
+ */
+export function extractRmTargets(command) {
+  if (typeof command !== "string") return [];
+  const trimmed = command.trim();
+  if (!RM_COMMAND_PATTERN.test(trimmed)) return [];
+
+  const parts = trimmed.split(/\s+/);
+  const targets = [];
+
+  // Skip leading "rm" and any option flags (-r, -f, -rf, --recursive, etc.)
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i];
+    if (part.startsWith("-")) {
+      continue;
+    }
+    // Stop if shell control operators occur
+    if (/[;&|]/.test(part)) {
+      break;
+    }
+    targets.push(part);
+  }
+
+  return targets;
+}
+
+/**
+ * Builds a reversible trash move command replacing destructive rm (#104).
+ *
+ * @param {string[]} targetPaths
+ * @param {string} trashDir
+ * @returns {string}
+ */
+export function buildTrashCommand(targetPaths, trashDir) {
+  if (!Array.isArray(targetPaths) || targetPaths.length === 0) {
+    return "";
+  }
+  const cleanTargets = targetPaths
+    .map((t) => String(t || "").trim())
+    .filter((t) => t.length > 0 && !t.startsWith("-"));
+
+  if (cleanTargets.length === 0) {
+    return "";
+  }
+
+  const quotedTargets = cleanTargets.map((t) => (t.includes(" ") ? `"${t}"` : t)).join(" ");
+  const normalizedTrash = String(trashDir || ".dsh/trash").trim();
+  const quotedTrash = normalizedTrash.includes(" ") ? `"${normalizedTrash}"` : normalizedTrash;
+
+  return `mkdir -p ${quotedTrash} && mv ${quotedTargets} ${quotedTrash}/`;
+}
+
+/**
+ * Suggests a safe trash alternative for an rm execution (#104).
+ *
+ * @param {string} command
+ * @param {string} [workspaceDir]
+ * @param {string} [sessionId]
+ * @returns {{ isRm: boolean, targets: string[], trashDir: string, suggestedCommand: string | null }}
+ */
+export function suggestTrashAlternative(command, workspaceDir, sessionId) {
+  const isRm = isRmCommand(command);
+  if (!isRm) {
+    return {
+      isRm: false,
+      targets: [],
+      trashDir: "",
+      suggestedCommand: null,
+    };
+  }
+
+  const targets = extractRmTargets(command);
+  const trashDir = resolveTrashDir(workspaceDir, sessionId);
+  const suggestedCommand = targets.length > 0 ? buildTrashCommand(targets, trashDir) : null;
+
+  return {
+    isRm: true,
+    targets,
+    trashDir,
+    suggestedCommand,
+  };
+}

package/lib/version-guard.js

@@ -0,0 +1,177 @@
+// lib/version-guard.js
+// Dependency version guard: detects unauthorized major dependency bumps in package.json (#95).
+
+import fs from "node:fs";
+import path from "node:path";
+
+const DEPENDENCY_SECTIONS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+];
+
+const SEMVER_REGEX = /^(?:[\^~>=<v\s]*?)(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
+
+/**
+ * Parses semver string into numeric major, minor, and patch components (#95).
+ *
+ * @param {string} ver
+ * @returns {{ major: number, minor: number, patch: number } | null}
+ */
+export function parseSemver(ver) {
+  if (typeof ver !== "string" || !ver.trim()) return null;
+  const match = SEMVER_REGEX.exec(ver.trim());
+  if (!match) return null;
+
+  return {
+    major: parseInt(match[1], 10),
+    minor: match[2] !== undefined ? parseInt(match[2], 10) : 0,
+    patch: match[3] !== undefined ? parseInt(match[3], 10) : 0,
+  };
+}
+
+/**
+ * Determines whether a version transition represents a major version bump (#95).
+ *
+ * @param {string} oldVer
+ * @param {string} newVer
+ * @returns {boolean}
+ */
+export function isMajorBump(oldVer, newVer) {
+  const oldParsed = parseSemver(oldVer);
+  const newParsed = parseSemver(newVer);
+  if (!oldParsed || !newParsed) return false;
+
+  return newParsed.major > oldParsed.major;
+}
+
+/**
+ * Compares two dependency maps and returns detected major bumps (#95).
+ *
+ * @param {Record<string, string>} [oldDeps]
+ * @param {Record<string, string>} [newDeps]
+ * @param {string} [section="dependencies"]
+ * @returns {Array<{ pkg: string, from: string, to: string, section: string }>}
+ */
+export function compareDependencySection(oldDeps = {}, newDeps = {}, section = "dependencies") {
+  if (!oldDeps || !newDeps) return [];
+  const bumps = [];
+
+  for (const [pkg, newVer] of Object.entries(newDeps)) {
+    const oldVer = oldDeps[pkg];
+    if (typeof oldVer === "string" && typeof newVer === "string") {
+      if (isMajorBump(oldVer, newVer)) {
+        bumps.push({
+          pkg,
+          from: oldVer,
+          to: newVer,
+          section,
+        });
+      }
+    }
+  }
+
+  return bumps;
+}
+
+/**
+ * Inspects a mutation between two package.json objects for major dependency bumps (#95).
+ *
+ * @param {any} oldPkg
+ * @param {any} newPkg
+ * @returns {{ hasMajorBump: boolean, bumps: Array<{ pkg: string, from: string, to: string, section: string }> }}
+ */
+export function inspectPackageJsonDiff(oldPkg, newPkg) {
+  if (!oldPkg || typeof oldPkg !== "object" || !newPkg || typeof newPkg !== "object") {
+    return { hasMajorBump: false, bumps: [] };
+  }
+
+  const allBumps = [];
+
+  for (const section of DEPENDENCY_SECTIONS) {
+    const oldSec = oldPkg[section] || {};
+    const newSec = newPkg[section] || {};
+    const sectionBumps = compareDependencySection(oldSec, newSec, section);
+    allBumps.push(...sectionBumps);
+  }
+
+  return {
+    hasMajorBump: allBumps.length > 0,
+    bumps: allBumps,
+  };
+}
+
+/**
+ * Guard enforcing human confirmation on major dependency version updates (#95).
+ */
+export class VersionGuard {
+  /**
+   * @param {{ workspaceDir?: string }} [options]
+   */
+  constructor(options = {}) {
+    this.workspaceDir = options.workspaceDir || "";
+  }
+
+  /**
+   * Inspects a file write operation to detect major dependency bumps in package.json (#95).
+   *
+   * @param {string} targetPath - Path of file being written
+   * @param {string | object} newContent - Incoming content or parsed JSON
+   * @returns {{ majorBump: boolean, bumps: Array<any>, detail?: string }}
+   */
+  inspectWrite(targetPath, newContent) {
+    if (typeof targetPath !== "string") {
+      return { majorBump: false, bumps: [] };
+    }
+
+    const basename = path.basename(targetPath);
+    if (basename !== "package.json") {
+      return { majorBump: false, bumps: [] };
+    }
+
+    let parsedNew;
+    if (typeof newContent === "string") {
+      try {
+        parsedNew = JSON.parse(newContent);
+      } catch {
+        return { majorBump: false, bumps: [] };
+      }
+    } else if (newContent && typeof newContent === "object") {
+      parsedNew = newContent;
+    } else {
+      return { majorBump: false, bumps: [] };
+    }
+
+    // Attempt reading existing package.json
+    let existingPkg = null;
+    const resolvedPath = path.isAbsolute(targetPath)
+      ? targetPath
+      : path.resolve(this.workspaceDir || process.cwd(), targetPath);
+
+    try {
+      if (fs.existsSync(resolvedPath)) {
+        const raw = fs.readFileSync(resolvedPath, "utf-8");
+        existingPkg = JSON.parse(raw);
+      }
+    } catch {
+      // ignore read/parse error on existing file
+    }
+
+    if (!existingPkg) {
+      return { majorBump: false, bumps: [] };
+    }
+
+    const diff = inspectPackageJsonDiff(existingPkg, parsedNew);
+    if (diff.hasMajorBump) {
+      const descriptions = diff.bumps.map((b) => `${b.pkg} (${b.from} -> ${b.to})`).join(", ");
+      return {
+        majorBump: true,
+        bumps: diff.bumps,
+        detail: `Major dependency version bump detected: ${descriptions}`,
+      };
+    }
+
+    return { majorBump: false, bumps: [] };
+  }
+}