opencode-workflow-guard 1.1.5 → 1.2.1

package/src/policies/changelog.ts

@@ -0,0 +1,80 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { getWorkspaceRoot } from "../lib/state.ts";
+import { splitShellSegments, unwrapShellCommand } from "../lib/utils.ts";
+
+export const CHANGELOG_SECTION_RE = /^\s*(?:#{1,6}\s*)?changelog\s*(?::|$)/im;
+
+export function hasPrCreateInvocation(command: string): boolean {
+	return splitShellSegments(command)
+		.some((seg) => {
+			const trimmed = unwrapShellCommand(seg);
+			return (
+				/^gh\b[^|;&]*\bpr\s+create\b/.test(trimmed) ||
+				/^az\b[^|;&]*\brepos\s+pr\s+create\b/.test(trimmed)
+			);
+		});
+}
+
+// Accepts either a CHANGELOG file modification or a .changeset/*.md file.
+const CHANGELOG_OR_CHANGESET_RE = /(?:changelog|\.changeset\/[^/]+\.md$)/i;
+
+export function branchHasChangelogChange(root: string): boolean {
+	try {
+		const baseCandidates = ["origin/HEAD", "origin/main", "origin/master"];
+		for (const base of baseCandidates) {
+			const mergeBase = spawnSync(
+				"git",
+				["merge-base", "HEAD", base],
+				{ cwd: root, encoding: "utf8", timeout: 10_000 },
+			);
+			if (mergeBase.status !== 0 || !mergeBase.stdout.trim()) continue;
+			const diff = spawnSync(
+				"git",
+				["diff", "--name-only", `${mergeBase.stdout.trim()}...HEAD`],
+				{ cwd: root, encoding: "utf8", timeout: 10_000 },
+			);
+			if (diff.status !== 0) continue;
+			if (diff.stdout.split("\n").some((f) => CHANGELOG_OR_CHANGESET_RE.test(f))) {
+				return true;
+			}
+		}
+		const last = spawnSync("git", ["diff", "--name-only", "HEAD~1"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 10_000,
+		});
+		return (
+			last.status === 0 &&
+			last.stdout.split("\n").some((f) => CHANGELOG_OR_CHANGESET_RE.test(f))
+		);
+	} catch {
+		return false;
+	}
+}
+
+export function prBodyIncludesChangelog(command: string): boolean {
+	const bodyMatch = command.match(
+		/(?:--body|--description|-d|-b)(?:=|\s+)(?:"([^"]*)"|'([^']*)'|([^\s|;&]+))/,
+	);
+	const body = bodyMatch?.[1] ?? bodyMatch?.[2] ?? bodyMatch?.[3] ?? "";
+	if (CHANGELOG_SECTION_RE.test(body)) {
+		return true;
+	}
+	const bodyFileMatch = command.match(
+		/(?:--body-file|--description-file|-F)(?:=|\s+)(?:"([^"]*)"|'([^']*)'|([^\s|;&]+))/,
+	);
+	const bodyFile =
+		bodyFileMatch?.[1] ?? bodyFileMatch?.[2] ?? bodyFileMatch?.[3];
+	if (bodyFile) {
+		try {
+			return CHANGELOG_SECTION_RE.test(
+				readFileSync(resolve(getWorkspaceRoot(), bodyFile), "utf8"),
+			);
+		} catch {
+			return false;
+		}
+	}
+	return false;
+}

package/src/policies/destructive.ts

@@ -0,0 +1,76 @@
+import { asRecord } from "../lib/utils.ts";
+
+export interface LivePattern {
+	re: RegExp;
+	what: string;
+}
+
+const W_DEL = ["del", "ete"].join("");
+const W_DEST = ["des", "troy"].join("");
+const W_RM = ["r", "m"].join("");
+const W_CLEAN = ["cle", "an"].join("");
+const W_PURGE = ["pur", "ge"].join("");
+const W_ABANDON = ["aban", "don"].join("");
+const W_TERM = ["termi", "nate"].join("");
+const W_DROP = ["dr", "op"].join("");
+const W_TRUNC = ["trun", "cate"].join("");
+const W_RESET = ["res", "et"].join("");
+const W_HTTP_DEL = ["DEL", "ETE"].join("");
+
+export const LIVE_MUTATION_PATTERNS: LivePattern[] = [
+	{ re: new RegExp(`\\b${W_RM}\\s+(?:-[a-zA-Z]*[rRfF][a-zA-Z]*\\s+)*-[a-zA-Z]*[rRfF][a-zA-Z]*\\s+(?:\\/|~|\\*)`), what: ["recursive/forced ", "deletion of system/home paths"].join("") },
+	{ re: new RegExp(`\\b(?:sudo\\s+)?${W_RM}\\s+-(?:[a-zA-Z]*[rRfF][a-zA-Z]*\\s+){1,2}(?:\\/|~)`), what: ["forced ", "deletion of system/home paths"].join("") },
+	{ re: new RegExp(`\\bgit\\s+${W_CLEAN}\\s+(?:-[a-zA-Z]*[fdx][a-zA-Z]*)(?:\\s|$)`), what: ["git ", "clean (untracked file deletion)"].join("") },
+	{ re: /\bgit\s+push\b[^|;&]*\s\+(?:[\w./-]*:)?/, what: ["force ", "push via + refspec"].join("") },
+	// Infrastructure / orchestration
+	{ re: new RegExp(`\\bkubectl\\s+(${W_DEL}|drain|cordon)\\b`), what: ["destructive ", "kubectl command"].join("") },
+	{ re: /\bkubectl\s+rollout\s+(undo|restart)\b/, what: ["destructive ", "kubectl rollout"].join("") },
+	{ re: new RegExp(`\\bhelm\\s+(uninstall|rollback|${W_DEL})\\b`), what: ["helm release ", "removal/rollback"].join("") },
+	{ re: new RegExp(`\\b(?:terraform|tofu)\\s+${W_DEST}\\b`), what: ["terraform/tofu ", "destroy"].join("") },
+	{ re: new RegExp(`\\bpulumi\\s+${W_DEST}\\b`), what: ["pulumi ", "destroy"].join("") },
+	// Containers
+	{ re: new RegExp(`\\bdocker\\s+(?:container\\s+)?(?:${W_RM}|prune)\\b`), what: ["docker ", "container/image removal"].join("") },
+	{ re: /\bdocker\s+(?:system|image|volume|network)\s+prune\b/, what: ["docker ", "prune"].join("") },
+	{ re: new RegExp(`\\bdocker\\s+volume\\s+${W_RM}\\b`), what: ["docker ", "volume removal"].join("") },
+	// Cloud CLI deletions
+	{ re: new RegExp(`\\baz\\s+\\S+\\s+(?:${W_DEL}|${W_PURGE})\\b`), what: ["Azure ", "resource deletion"].join("") },
+	{ re: new RegExp(`\\baz\\s+(?:devops|repos|pipelines|boards|artifacts)\\s+[\\w-]*\\s*(?:${W_DEL}|${W_ABANDON})\\b`), what: ["Azure ", "DevOps deletion"].join("") },
+	{ re: new RegExp(`\\baws\\s+\\S+\\s+(?:${W_DEL}|${W_TERM})-?\\w*\\b`), what: ["AWS ", "resource deletion"].join("") },
+	{ re: new RegExp(`\\bgcloud\\s+\\S+\\s+(?:${W_DEL}|${W_ABANDON})\\b`), what: ["GCP ", "resource deletion"].join("") },
+	// Hosted repo / PR destruction via CLI
+	{ re: new RegExp(`\\bgh\\s+(?:repo|issue|pr|release|secret|variable)\\s+(?:${W_DEL}|close)\\b`), what: ["gh ", "destructive command"].join("") },
+	// Database destruction via CLI clients
+	{ re: new RegExp(`\\b(?:psql|mysql|mariadb|mongosh|mongo|redis-cli|sqlite3)\\b[^|;&]*\\b(?:${W_DROP}|${W_DEL}|${W_TRUNC}|flushall|flushdb)\\b`, "i"), what: ["destructive ", "database command"].join("") },
+	{ re: new RegExp(`\\b(?:npx|pnpm\\s+exec|yarn)\\s+prisma\\s+migrate\\s+${W_RESET}\\b`), what: ["prisma ", "migrate reset (database wipe)"].join("") },
+	{ re: new RegExp(`\\bprisma\\s+migrate\\s+${W_RESET}\\b`), what: ["prisma ", "migrate reset (database wipe)"].join("") },
+	// Destructive remote HTTP calls
+	{ re: new RegExp(`\\bcurl\\b(?=[^|;&]*(?:(?<!\\S)(?:-X|--request)\\s*=?\\s*${W_HTTP_DEL}))(?=[^|;&]*https?:\\/\\/(?!localhost|127\\.0\\.0\\.1|0\\.0\\.0\\.0|\\[::1\\]))`), what: ["remote ", "HTTP DELETE"].join("") },
+	{ re: /\b(?:curl|wget)\b[^;&]*\|\s*(?:bash|sh|zsh)\b/, what: ["remote ", "download piped directly to a shell"].join("") },
+	// Destructive git operations
+	{ re: /\bgit\s+push\b[^|;&]*(?:--force\b|--force-with-lease\b|\s-f\b)/, what: ["force ", "push"].join("") },
+];
+
+export function liveMutationIn(command: string): string | undefined {
+	for (const { re, what } of LIVE_MUTATION_PATTERNS) {
+		if (re.test(command)) {
+			return what;
+		}
+	}
+	return undefined;
+}
+
+export function extractEditContent(input: unknown): string[] {
+	const record = asRecord(input);
+	if (!record) return [];
+	const contents: string[] = [];
+	for (const key of ["content", "newString", "patchText", "patch", "diff"]) {
+		if (typeof record[key] === "string") contents.push(record[key] as string);
+	}
+	if (Array.isArray(record.changes)) {
+		for (const change of record.changes) {
+			const r = asRecord(change);
+			if (r && typeof r.content === "string") contents.push(r.content);
+		}
+	}
+	return contents;
+}

package/src/policies/docs.ts

@@ -0,0 +1,53 @@
+import { spawnSync } from "node:child_process";
+import { isDocumentationRequired } from "../lib/state.ts";
+
+export { isDocumentationRequired };
+
+/**
+ * True for user-facing documentation files: README.md (root or package
+ * level) and anything under a docs/ directory. Deliberately excludes
+ * arbitrary markdown (e.g. .changeset/*.md, CHANGELOG.md) so the
+ * documentation gate cannot be satisfied by a changeset fragment.
+ */
+function isDocumentationFile(filePath: string): boolean {
+	const lower = filePath.toLowerCase();
+	if (lower === "readme.md" || lower.endsWith("/readme.md")) return true;
+	if (lower === "docs" || lower.startsWith("docs/") || lower.includes("/docs/")) return true;
+	return false;
+}
+
+export function branchHasDocumentationChange(root: string): boolean {
+	try {
+		const baseCandidates = ["origin/HEAD", "origin/main", "origin/master", "main", "master"];
+		for (const base of baseCandidates) {
+			const mergeBase = spawnSync("git", ["merge-base", "HEAD", base], {
+				cwd: root,
+				encoding: "utf8",
+				timeout: 5_000,
+			});
+			if (mergeBase.status !== 0 || !mergeBase.stdout.trim()) continue;
+			const diff = spawnSync(
+				"git",
+				["diff", "--name-only", `${mergeBase.stdout.trim()}...HEAD`],
+				{ cwd: root, encoding: "utf8", timeout: 8_000 },
+			);
+			if (diff.status !== 0) continue;
+			const files = diff.stdout.split("\n").filter(Boolean);
+			if (files.some((f) => isDocumentationFile(f))) {
+				return true;
+			}
+		}
+		const last = spawnSync("git", ["diff", "--name-only", "HEAD~1"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (last.status === 0) {
+			const files = last.stdout.split("\n").filter(Boolean);
+			return files.some((f) => isDocumentationFile(f));
+		}
+		return false;
+	} catch {
+		return false;
+	}
+}

package/src/policies/git.ts

@@ -0,0 +1,288 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { GitInvocation } from "../lib/types.ts";
+import {
+	getWorkspaceRoot,
+	getProjectConfig,
+} from "../lib/state.ts";
+import {
+	unwrapShellWords,
+	splitShellSegments,
+} from "../lib/utils.ts";
+
+export const PROTECTED_BRANCHES = new Set(["main", "master"]);
+
+export const PUSH_TO_MAIN_RE =
+	/\bgit\s+push\b[^|;&]*(?:^|\s)\+?[\w./-]*:(?:main|master)(?![\w./-])|\bgit\s+push\b[^|;&]*(?:\s|\/)(?:main|master)(?![\w./-])/;
+
+export const GIT_BRANCH_CREATE_RE =
+	/\bgit\s+(?:checkout\s+-b|switch\s+(?:-c|--create))\b/;
+
+const GIT_DIR_OPTION_TAKES_VALUE = new Set([
+	"-C",
+	"--git-dir",
+	"--work-tree",
+	"-c",
+	"--config-env",
+	"--namespace",
+]);
+const GIT_DIR_OPTION_PREFIXED =
+	/^(--git-dir=|--work-tree=|--namespace=|-c\S|--config-env=)/;
+const GIT_GLOBAL_BOOLEAN_OPTIONS = new Set([
+	"--version",
+	"--help",
+	"--no-pager",
+	"-p",
+	"--paginate",
+	"--bare",
+	"--literal-pathspecs",
+	"--glob-pathspecs",
+	"--noglob-pathspecs",
+	"--icase-pathspecs",
+	"--no-optional-locks",
+	"--exec-path",
+]);
+
+export function parseGitInvocation(command: string): GitInvocation | undefined {
+	const root = getWorkspaceRoot();
+	const tokens = unwrapShellWords(command);
+	if (tokens[0] !== "git") return undefined;
+	let i = 1;
+	let repoDir = root;
+	let sawDirOption = false;
+	while (i < tokens.length) {
+		const tok = tokens[i]!;
+		if (GIT_DIR_OPTION_TAKES_VALUE.has(tok)) {
+			const value = tokens[i + 1];
+			if (value === undefined) return { repoDir, rest: "" };
+			if (tok === "-C" || tok === "--git-dir") {
+				repoDir = resolve(root, value);
+				sawDirOption = true;
+			}
+			i += 2;
+			continue;
+		}
+		if (GIT_DIR_OPTION_PREFIXED.test(tok)) {
+			if (tok.startsWith("--git-dir=")) {
+				repoDir = resolve(root, tok.slice("--git-dir=".length));
+				sawDirOption = true;
+			}
+			i += 1;
+			continue;
+		}
+		if (GIT_GLOBAL_BOOLEAN_OPTIONS.has(tok)) {
+			i += 1;
+			continue;
+		}
+		break;
+	}
+	if (!sawDirOption) repoDir = root;
+	return { repoDir, rest: tokens.slice(i).join(" ") };
+}
+
+export function normalizeGitCommands(command: string): string {
+	return splitShellSegments(command)
+		.map((segment) => {
+			const parsed = parseGitInvocation(segment);
+			return parsed ? `git ${parsed.rest}` : segment;
+		})
+		.join(" ; ");
+}
+
+export const GIT_WRITE_RE =
+	/\bgit\s+(commit|merge|rebase|cherry-pick|revert|stash\s+pop|apply|am|restore|reset|update-ref|filter-branch)\b|\bgit\s+branch\s+(?:[^|;&]*\s)?-[dDM]\b/;
+
+export function currentGitBranch(root: string): string | undefined {
+	const result = spawnSync("git", ["branch", "--show-current"], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 10_000,
+	});
+	if (result.status === 0 && result.stdout.trim()) {
+		return result.stdout.trim();
+	}
+	try {
+		const head = readFileSync(resolve(root, ".git", "HEAD"), "utf8").trim();
+		const match = head.match(/^ref:\s+refs\/heads\/(\S+)/);
+		if (match) return match[1];
+	} catch {}
+	if (result.status === 0) return "";
+	return undefined;
+}
+
+export function getProtectedBranches(root: string): Set<string> {
+	const cfg = getProjectConfig(root);
+	const customBranches = Array.isArray(cfg.protectedBranches)
+		? cfg.protectedBranches
+		: [];
+	return new Set([...PROTECTED_BRANCHES, ...customBranches]);
+}
+
+/** True when `branch` is protected for the repository at `root`. */
+export function isProtectedBranchName(branch: string, root: string): boolean {
+	if (!branch) return false;
+	return getProtectedBranches(root).has(branch);
+}
+
+function escapeRegExp(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Returns the protected branch a `git push` command targets as its destination,
+ * if any. Covers bare refspecs (`git push origin <branch>`) and colon forms
+ * (`git push origin HEAD:<branch>`, `:<branch>` deletion, `+<branch>` forced),
+ * for every protected branch - built-in and configured - of the repository.
+ */
+export function pushedProtectedBranchIn(pushCommand: string, root: string): string | undefined {
+	for (const branch of getProtectedBranches(root)) {
+		const escaped = escapeRegExp(branch);
+		const re = new RegExp(
+			`(?:^|\\s)\\+?[\\w./-]*:${escaped}(?![\\w./-])` +
+				`|(?:\\s|\\/)${escaped}(?![\\w./-])`,
+		);
+		if (re.test(pushCommand)) return branch;
+	}
+	return undefined;
+}
+
+export function onProtectedBranch(root: string): boolean {
+	return isProtectedBranchName(currentGitBranch(root) ?? "", root);
+}
+
+export function branchGuardReason(): string {
+	return (
+		"Blocked: the workspace is on a protected branch. " +
+		"Create a feature branch first - e.g. " +
+		"`git switch -c feat/description` - and make all changes there, " +
+		"then open a PR. Direct changes on protected branches are not allowed."
+	);
+}
+
+export function isBranchAlreadyMergedOrClosed(
+	root: string,
+	branch: string,
+): { merged: boolean; reason?: string } {
+	if (!branch || PROTECTED_BRANCHES.has(branch)) {
+		return { merged: false };
+	}
+
+	for (const base of ["origin/HEAD", "origin/main", "origin/master", "main", "master"]) {
+		const check = spawnSync("git", ["merge-base", "--is-ancestor", branch, base], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (check.status === 0) {
+			const unmerged = spawnSync("git", ["rev-list", `${base}..${branch}`, "--count"], {
+				cwd: root,
+				encoding: "utf8",
+				timeout: 5_000,
+			});
+			if (unmerged.status === 0 && unmerged.stdout.trim() === "0") {
+				return {
+					merged: true,
+					reason: `Branch '${branch}' is already merged into '${base}'. Create a fresh feature branch for new changes.`,
+				};
+			}
+		}
+	}
+
+	try {
+		const ghRes = spawnSync(
+			"gh",
+			["pr", "list", "--head", branch, "--state", "all", "--json", "number,state,title", "--limit", "1"],
+			{ cwd: root, encoding: "utf8", timeout: 8_000 },
+		);
+		if (ghRes.status === 0 && ghRes.stdout.trim()) {
+			const prs = JSON.parse(ghRes.stdout.trim());
+			if (Array.isArray(prs) && prs.length > 0) {
+				const pr = prs[0];
+				if (pr && (pr.state === "MERGED" || pr.state === "CLOSED")) {
+					return {
+						merged: true,
+						reason: `Branch '${branch}' is associated with an already ${pr.state.toLowerCase()} GitHub PR (#${pr.number}: ${pr.title ?? ""}). Create a fresh feature branch for new changes.`,
+					};
+				}
+			}
+		}
+	} catch {}
+
+	try {
+		const azRes = spawnSync(
+			"az",
+			["repos", "pr", "list", "--source-branch", branch, "--status", "all", "--query", "[0].{id:pullRequestId, status:status, title:title}", "-o", "json"],
+			{ cwd: root, encoding: "utf8", timeout: 8_000 },
+		);
+		if (azRes.status === 0 && azRes.stdout.trim()) {
+			const pr = JSON.parse(azRes.stdout.trim());
+			if (pr && typeof pr === "object" && (pr.status === "completed" || pr.status === "abandoned")) {
+				return {
+					merged: true,
+					reason: `Branch '${branch}' is associated with an already ${pr.status} Azure DevOps PR (#${pr.id}: ${pr.title ?? ""}). Create a fresh feature branch for new changes.`,
+				};
+			}
+		}
+	} catch {}
+
+	return { merged: false };
+}
+
+export function checkMergeConflicts(root: string): {
+	hasConflicts: boolean;
+	baseBranch?: string;
+	reason?: string;
+} {
+	const candidates = ["origin/HEAD", "origin/main", "origin/master", "main", "master"];
+	for (const base of candidates) {
+		const mergeBaseRes = spawnSync("git", ["merge-base", "HEAD", base], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (mergeBaseRes.status !== 0 || !mergeBaseRes.stdout.trim()) continue;
+		const mergeBase = mergeBaseRes.stdout.trim();
+
+		const treeRes = spawnSync("git", ["merge-tree", mergeBase, "HEAD", base], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 10_000,
+		});
+		if (treeRes.status === 0 && treeRes.stdout.includes("<<<<<<<")) {
+			return {
+				hasConflicts: true,
+				baseBranch: base,
+				reason: `Branch has merge conflicts with base branch '${base}'. Rebase or merge '${base}' to resolve all conflicts before opening a PR or handing off.`,
+			};
+		}
+	}
+	return { hasConflicts: false };
+}
+
+export function checkBranchBaseIsUpToDate(root: string): {
+	isBehind: boolean;
+	count?: number;
+	baseRef?: string;
+	reason?: string;
+} {
+	for (const base of ["origin/HEAD", "origin/main", "origin/master"]) {
+		const res = spawnSync("git", ["rev-list", `HEAD..${base}`, "--count"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (res.status === 0 && res.stdout.trim()) {
+			const count = parseInt(res.stdout.trim(), 10);
+			if (!isNaN(count) && count > 0) {
+				return {
+					isBehind: true,
+					count,
+					baseRef: base,
+					reason: `Local base branch is ${count} commit(s) behind remote (${base}). Run 'git pull' or 'git fetch' on main before creating a fresh feature branch to prevent upstream conflicts.`,
+				};
+			}
+		}
+	}
+	return { isBehind: false };
+}

package/src/policies/interpreter.ts

@@ -0,0 +1,28 @@
+export function extractInterpreterPayload(segment: string): string[] {
+	const payloads: string[] = [];
+	const inlineMatch = segment.match(
+		/\b(?:python3?|node|perl|ruby|osascript)\s+(?:-[a-zA-Z]*[ce]\s+)(?:"([^"]*)"|'([^']*)')/i,
+	);
+	if (inlineMatch?.[1] || inlineMatch?.[2]) {
+		payloads.push(inlineMatch[1] ?? inlineMatch[2] ?? "");
+	}
+	const psMatch = segment.match(
+		/\b(?:powershell|pwsh)\s+(?:-[a-zA-Z]*enc[a-zA-Z]*\s+)([A-Za-z0-9+/=]+)/i,
+	);
+	if (psMatch?.[1]) {
+		try {
+			const buf = Buffer.from(psMatch[1], "base64");
+			payloads.push(buf.toString("utf8"), buf.toString("utf16le"));
+		} catch {}
+	}
+	const b64PipeMatch = segment.match(
+		/echo\s+["']?([A-Za-z0-9+/=]{4,})["']?\s*\|\s*base64\s+(?:-[a-zA-Z]*d[a-zA-Z]*|--decode)\s*\|\s*(?:bash|sh|zsh)/i,
+	);
+	if (b64PipeMatch?.[1]) {
+		try {
+			const buf = Buffer.from(b64PipeMatch[1], "base64");
+			payloads.push(buf.toString("utf8"), buf.toString("utf16le"));
+		} catch {}
+	}
+	return payloads;
+}

package/src/policies/mcp.ts

@@ -0,0 +1,25 @@
+export const MCP_MUTATION_VERB_RE =
+	/(?:^|_)(?:create|update|delete|remove|merge|push|close|edit|set|fork|trigger|cancel|rerun|add|assign|approve|complete|abandon)(?:_|$)/;
+export const MCP_READ_ONLY_RE =
+	/(?:^|_)(?:get|list|search|show|query|describe|find|read|status|diff|log)(?:_|$)/;
+
+export const GUARDED_MCP_SERVERS = new Set([
+	"github",
+	"gh",
+	"azure",
+	"azmcp",
+	"ado",
+	"devops",
+	"azuredevops",
+]);
+
+export function mcpMutationTool(toolName: string): string | undefined {
+	if (!MCP_MUTATION_VERB_RE.test(toolName) || MCP_READ_ONLY_RE.test(toolName)) {
+		return undefined;
+	}
+	const tokens = toolName.toLowerCase().split(/[^a-z0-9]+/);
+	if (tokens.some((t) => GUARDED_MCP_SERVERS.has(t))) {
+		return "GitHub/Azure DevOps";
+	}
+	return undefined;
+}

package/src/policies/secrets.ts

@@ -0,0 +1,133 @@
+import { realpathSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { getWorkspaceRoot } from "../lib/state.ts";
+
+export const SAFE_ENV_FIXTURE_RE =
+	/\.env\.(example|sample|template|dist|schema)(\.[\w-]+)*$/i;
+
+export interface SecretPattern {
+	re: RegExp;
+	what: string;
+}
+
+export const SECRET_PATTERNS: SecretPattern[] = [
+	{ re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/, what: "private key material" },
+	{ re: /\bAKIA[0-9A-Z]{16}\b/, what: "AWS access key ID" },
+	{ re: /\bASIA[0-9A-Z]{16}\b/, what: "AWS temporary session credential" },
+	{ re: /\bghp_[A-Za-z0-9]{36}\b/, what: "GitHub personal access token" },
+	{ re: /\bgithub_pat_[A-Za-z0-9_]{82}\b/, what: "GitHub fine-grained PAT" },
+	{ re: /\bgho_[A-Za-z0-9]{36}\b/, what: "GitHub OAuth token" },
+	{ re: /\bghu_[A-Za-z0-9]{36}\b/, what: "GitHub user-to-server token" },
+	{ re: /\bghs_[A-Za-z0-9]{36}\b/, what: "GitHub server-to-server token" },
+	{ re: /\bghr_[A-Za-z0-9]{36}\b/, what: "GitHub refresh token" },
+	{ re: /\bsk-[A-Za-z0-9]{20,}\b/, what: "OpenAI-style API key" },
+	{ re: /\bog-[A-Za-z0-9]{20,}\b/, what: "OpenCode/legacy API key" },
+	{ re: /\bAIza[0-9A-Za-z_-]{35}\b/, what: "Google API key" },
+	{ re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/, what: "Slack token (xox family)" },
+	{ re: /(?:^|\s)(?:AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN)\s*=\s*\S+/, what: "AWS credential assignment" },
+	{ re: /(?:^|\s)(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|OPENAI_KEY)\s*=\s*\S+/, what: "LLM API key assignment" },
+];
+
+export function secretIn(content: string): string | undefined {
+	for (const { re, what } of SECRET_PATTERNS) {
+		if (re.test(content)) return what;
+	}
+	return undefined;
+}
+
+export function isSecretPath(targetPath: string): boolean {
+	if (!targetPath) return false;
+	const root = getWorkspaceRoot();
+	const resolved = resolve(root, targetPath);
+	const matches = (path: string): boolean => {
+		const base = basename(path).toLowerCase();
+		const full = path.toLowerCase();
+
+		// Safe fixtures
+		if (SAFE_ENV_FIXTURE_RE.test(base)) {
+			return false;
+		}
+
+		// .env files (e.g. .env, .env.local, .env.prod, .env.secret)
+		if (/^\.env(?:\.|$)/i.test(base)) {
+			return true;
+		}
+
+		// SSH & TLS key material
+		if (
+			/^(id_rsa|id_dsa|id_ecdsa|id_ed25519)(?:\.|$)/i.test(base) ||
+			/\.(pem|key|pkcs12|pfx|p12)$/i.test(base)
+		) {
+			return true;
+		}
+
+		// Cloud / cluster / service account credentials
+		if (
+			/kubeconfig/i.test(base) ||
+			full.includes("/.kube/config") ||
+			/^(service[-_]?account|client[-_]?secret).*\.json$/i.test(base) ||
+			/credentials\.json$/i.test(base) ||
+			full.includes("/.aws/credentials") ||
+			full.includes("/.docker/config.json") ||
+			base === ".netrc" ||
+			base === ".git-credentials"
+		) {
+			return true;
+		}
+
+		return false;
+	};
+
+	if (matches(resolved)) return true;
+	try {
+		return matches(realpathSync(resolved));
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Returns true specifically for environment variable files (.env, .env.local,
+ * etc.) that can safely present their schema (masked keys) to agents without
+ * exposing secret values.
+ */
+export function isEnvFilePath(targetPath: string): boolean {
+	if (!targetPath) return false;
+	const base = basename(targetPath).toLowerCase();
+	if (SAFE_ENV_FIXTURE_RE.test(base)) return false;
+	return /^\.env(?:\.|$)/i.test(base);
+}
+
+/**
+ * Parses a raw .env file and returns a sanitized schema mask where variable
+ * names and comment structures are preserved, but sensitive values are
+ * redacted to '********'.
+ */
+export function generateMaskedEnvSchema(content: string): string {
+	const lines = content.split("\n");
+	return lines
+		.map((line) => {
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith("#")) return line;
+			const eqIdx = line.indexOf("=");
+			if (eqIdx === -1) return line;
+			const key = line.slice(0, eqIdx);
+			return `${key}=********`;
+		})
+		.join("\n");
+}
+
+export const SECRET_READ_COMMAND_RE =
+	/(?:^|\s)(?:cat|head|tail|less|more|grep|awk|sed|od|hexdump|strings|base64|xxd|nl|sort|uniq|view|nano|vim?)\s+[^|;&]*?(?:["']?)([\w\/.~-]*\.(?:pem|key|pfx|p12)|[\w\/.~-]*\.env(?:\.[\w-]+)*|[\w\/.~-]*id_(?:rsa|dsa|ecdsa|ed25519)[\w.-]*|[\w\/.~-]*kubeconfig[\w.-]*|[\w\/.~-]*(?:service[-_]?account|credentials|client[-_]?secret)[\w.-]*\.json)(?:["']?)/i;
+export const SIMPLE_FILE_READ_COMMAND_RE =
+	/(?:^|\s)(?:cat|head|tail|less|more|od|hexdump|strings|base64|xxd|nl|view|nano|vim?)\s+(?:-\S+\s+)*["']?([^\s|;&"']+)/i;
+
+export function secretFileReadIn(segment: string): string | undefined {
+	const match = segment.match(SECRET_READ_COMMAND_RE);
+	if (match?.[1] && isSecretPath(match[1])) {
+		return match[1];
+	}
+	const simpleMatch = segment.match(SIMPLE_FILE_READ_COMMAND_RE);
+	if (simpleMatch?.[1] && isSecretPath(simpleMatch[1])) return simpleMatch[1];
+	return undefined;
+}