opencode-worktree-guardian 0.1.0

package/src/guards/git-invocation.ts

@@ -0,0 +1,145 @@
+import path from "node:path";
+import type { GuardOptions } from "../types.ts";
+import type { CommandPrefix, CommandSegment, GitInvocation } from "./guard-types.ts";
+import { peelCommandPrefix } from "./shell-prefix.ts";
+
+const GIT_GLOBAL_OPTIONS_WITH_VALUE = new Set(["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--config-env", "--exec-path"]);
+const GIT_PUSH_OPTIONS_WITH_VALUE = new Set(["--repo", "--receive-pack", "--exec", "--push-option", "--recurse-submodules", "-o"]);
+
+function peelGitCommandPrefix(segment: CommandSegment): CommandPrefix {
+  return peelCommandPrefix(segment);
+}
+
+function assignmentMap(assignments: readonly string[]): ReadonlyMap<string, string> {
+  const map = new Map<string, string>();
+  for (const assignment of assignments) {
+    const equals = assignment.indexOf("=");
+    if (equals > 0) map.set(assignment.slice(0, equals), assignment.slice(equals + 1));
+  }
+  return map;
+}
+
+export function envConfigAliases(assignments: readonly string[]): string[] {
+  const env = assignmentMap(assignments);
+  const count = Number(env.get("GIT_CONFIG_COUNT") ?? 0);
+  const configs: string[] = [];
+  if (!Number.isInteger(count) || count <= 0) return configs;
+  for (let index = 0; index < count; index += 1) {
+    const key = env.get(`GIT_CONFIG_KEY_${index}`);
+    const value = env.get(`GIT_CONFIG_VALUE_${index}`) ?? "";
+    if (typeof key === "string") configs.push(`${key}=${value}`);
+  }
+  return configs;
+}
+
+export function hasAliasCapableRuntimeConfig(configs: readonly string[]): boolean {
+  return configs.some((config) => {
+    const key = config.slice(0, config.indexOf("=")).toLowerCase();
+    return key.startsWith("alias.") || key === "include.path" || key.startsWith("includeif.") && key.endsWith(".path");
+  });
+}
+
+export function parseGitInvocation(segment: CommandSegment, options: GuardOptions = {}): GitInvocation | null {
+  const { stripped, assignments } = peelGitCommandPrefix(segment);
+  if (stripped[0] !== "git") return null;
+  let index = 1;
+  let gitCwd: string | null = null;
+  let workTree: string | null = null;
+  const inheritedAssignments = Array.isArray(options.inheritedEnvAssignments) ? options.inheritedEnvAssignments.filter((entry: unknown) => typeof entry === "string") : [];
+  const configs: string[] = envConfigAliases([...inheritedAssignments, ...assignments]);
+  while (index < stripped.length) {
+    const token = stripped[index] ?? "";
+    if (!token.startsWith("-")) break;
+    if (token === "-C") {
+      const nextCwd = stripped[index + 1] ?? null;
+      if (nextCwd) {
+        gitCwd = gitCwd && !path.isAbsolute(nextCwd) ? path.join(gitCwd, nextCwd) : nextCwd;
+      }
+      index += 2;
+      continue;
+    }
+    if (token === "-c") {
+      if (stripped[index + 1]) configs.push(stripped[index + 1] ?? "");
+      index += 2;
+      continue;
+    }
+    if (token.startsWith("-c") && token.length > 2) {
+      configs.push(token.slice(2));
+      index += 1;
+      continue;
+    }
+    if (token === "--config-env") {
+      if (stripped[index + 1]) configs.push(stripped[index + 1] ?? "");
+      index += 2;
+      continue;
+    }
+    if (token.startsWith("--config-env=")) {
+      configs.push(token.slice("--config-env=".length));
+      index += 1;
+      continue;
+    }
+    if (token === "--work-tree") {
+      workTree = stripped[index + 1] ?? null;
+      index += 2;
+      continue;
+    }
+    if (token.startsWith("--work-tree=")) {
+      workTree = token.slice("--work-tree=".length);
+      index += 1;
+      continue;
+    }
+    if (GIT_GLOBAL_OPTIONS_WITH_VALUE.has(token)) {
+      index += 2;
+      continue;
+    }
+    if (token.startsWith("--config=")) {
+      configs.push(token.slice("--config=".length));
+      index += 1;
+      continue;
+    }
+    if ([...GIT_GLOBAL_OPTIONS_WITH_VALUE].some((option) => token.startsWith(`${option}=`))) {
+      index += 1;
+      continue;
+    }
+    index += 1;
+  }
+  return { subcommand: stripped[index], rest: stripped.slice(index + 1), normalized: stripped, gitCwd, workTree, configs };
+}
+
+export function pushRefspecs(rest: CommandSegment): string[] {
+  let index = 0;
+  let repoOption = false;
+  while (index < rest.length) {
+    const token = rest[index] ?? "";
+    if (token === "--") {
+      index += 1;
+      break;
+    }
+    if (!token.startsWith("-")) break;
+    if (token === "--repo") {
+      repoOption = true;
+      index += 2;
+      continue;
+    }
+    if (token.startsWith("--repo=")) {
+      repoOption = true;
+      index += 1;
+      continue;
+    }
+    if (GIT_PUSH_OPTIONS_WITH_VALUE.has(token)) {
+      index += 2;
+      continue;
+    }
+    if ([...GIT_PUSH_OPTIONS_WITH_VALUE].some((option) => token.startsWith(`${option}=`))) {
+      index += 1;
+      continue;
+    }
+    index += 1;
+  }
+  if (!repoOption && index < rest.length) index += 1;
+  return rest.slice(index).filter((token) => token && !token.startsWith("-"));
+}
+
+export function isForcePushToken(token: string): boolean {
+  return token === "--force" || token.startsWith("--force=") || token === "--force-with-lease" || token.startsWith("--force-with-lease=") || token === "-f";
+}

package/src/guards/guard-types.ts

@@ -0,0 +1,36 @@
+import type { GuardDecision } from "../types.ts";
+
+export type CommandToken = string;
+export type CommandSegment = readonly CommandToken[];
+export type MutableCommandSegment = CommandToken[];
+export type SegmentSeparator = ";" | "&&" | "||" | "|" | "(" | ")";
+
+export type SegmentWithSeparator = {
+  readonly segment: CommandSegment;
+  readonly nextSeparator: SegmentSeparator | null;
+};
+
+export type ShellPayload = {
+  readonly payload: string;
+  readonly assignments: readonly string[];
+};
+
+export type CommandPrefix = {
+  readonly stripped: CommandSegment;
+  readonly assignments: readonly string[];
+};
+
+export type GitInvocation = {
+  readonly subcommand: string | undefined;
+  readonly rest: CommandSegment;
+  readonly normalized: CommandSegment;
+  readonly gitCwd: string | null;
+  readonly workTree: string | null;
+  readonly configs: readonly string[];
+};
+
+export type GuardBlockDecision = GuardDecision & {
+  readonly blocked: true;
+  readonly reason: string;
+  readonly segment: CommandSegment;
+};

package/src/guards/options.ts

@@ -0,0 +1,15 @@
+import type { GuardOptions } from "../types.ts";
+import { nonEmptyString, stringArray } from "../types.ts";
+import type { CommandSegment, GuardBlockDecision } from "./guard-types.ts";
+
+export function block(reason: string, segment: CommandSegment): GuardBlockDecision {
+  return { blocked: true, reason, command: segment.join(" "), segment };
+}
+
+export function stringArrayOption(options: GuardOptions, key: keyof GuardOptions): string[] {
+  return stringArray(options[key]);
+}
+
+export function stringOption(options: GuardOptions, key: keyof GuardOptions): string | null {
+  return nonEmptyString(options[key]);
+}

package/src/guards/path-policy.ts

@@ -0,0 +1,31 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function normalizeForCompare(value: string, cwd: string): string {
+  const resolved = path.resolve(cwd, value);
+  return path.normalize(resolved);
+}
+
+export function realpathForCompare(value: string, cwd: string): string {
+  const normalized = normalizeForCompare(value, cwd);
+  try {
+    return path.normalize(fs.realpathSync.native(normalized));
+  } catch {
+    return normalized;
+  }
+}
+
+export function isSameOrInside(candidate: string, knownPath: string): boolean {
+  const relative = path.relative(knownPath, candidate);
+  return relative === "" || Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+export function pathSameOrInside(candidate: string, target: string, cwd: string): boolean {
+  return isSameOrInside(realpathForCompare(candidate, cwd), realpathForCompare(target, cwd));
+}
+
+export function matchesKnownWorktreePath(candidate: string, knownWorktreePaths: readonly string[], cwd: string): boolean {
+  if (!candidate || candidate.startsWith("-")) return false;
+  const resolvedCandidate = normalizeForCompare(candidate, cwd);
+  return knownWorktreePaths.some((knownPath) => isSameOrInside(resolvedCandidate, normalizeForCompare(knownPath, cwd)));
+}

package/src/guards/protected-branch-policy.ts

@@ -0,0 +1,88 @@
+import path from "node:path";
+import type { GuardOptions } from "../types.ts";
+import type { CommandSegment, GuardBlockDecision } from "./guard-types.ts";
+import { hasAliasCapableRuntimeConfig, pushRefspecs } from "./git-invocation.ts";
+import { block, stringArrayOption, stringOption } from "./options.ts";
+import { pathSameOrInside } from "./path-policy.ts";
+
+function branchNameFromRef(ref: string): string {
+  return ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+}
+
+function isProtectedRef(ref: string, protectedBranches: readonly string[]): boolean {
+  return protectedBranches.includes(branchNameFromRef(ref));
+}
+
+function isGuardianRef(ref: string, branchPrefix: string | null, guardianBranches: readonly string[]): boolean {
+  const branch = branchNameFromRef(ref);
+  return guardianBranches.includes(branch) || Boolean(branchPrefix && branch.startsWith(branchPrefix));
+}
+
+function isProtectedWorktreeTarget(target: string, worktreePaths: readonly string[], cwd: string): boolean {
+  return worktreePaths.some((worktreePath) => pathSameOrInside(target, worktreePath, cwd));
+}
+
+export function protectedBranchBypass(
+  segment: CommandSegment,
+  subcommand: string,
+  rest: CommandSegment,
+  options: GuardOptions,
+  gitCwd: string | null,
+  workTree: string | null,
+  configs: readonly string[],
+): GuardBlockDecision | null {
+  const protectedBranches = stringArrayOption(options, "protectedBranches");
+  const branchPrefix = stringOption(options, "branchPrefix");
+  const guardianBranches = stringArrayOption(options, "guardianBranches");
+  const protectedBranchWorktreePaths = stringArrayOption(options, "protectedBranchWorktreePaths");
+  if (protectedBranches.length === 0) return null;
+
+  if (subcommand === "push") {
+    const deletesBranch = rest.includes("--delete") || rest.includes("-d");
+    for (const rawSpec of pushRefspecs(rest)) {
+      const spec = rawSpec.startsWith("+") ? rawSpec.slice(1) : rawSpec;
+      const colon = spec.indexOf(":");
+      if (colon === -1) {
+        if (deletesBranch && isProtectedRef(spec, protectedBranches)) {
+          return block("protected branch deletion push is blocked", segment);
+        }
+        continue;
+      }
+      const source = spec.slice(0, colon);
+      const target = spec.slice(colon + 1);
+      if (!source && target && isProtectedRef(target, protectedBranches)) {
+        return block("protected branch deletion push is blocked", segment);
+      }
+      if (target && isProtectedRef(target, protectedBranches) && (source === "HEAD" || isGuardianRef(source, branchPrefix, guardianBranches))) {
+        return block("manual push from Guardian work to a protected branch is blocked; use guardian_finish", segment);
+      }
+    }
+  }
+
+  if (subcommand === "merge") {
+    const currentBranch = stringOption(options, "currentBranch");
+    const cwd = stringOption(options, "cwd") ?? process.cwd();
+    const gitTargetCwd = gitCwd ? path.resolve(cwd, gitCwd) : null;
+    const gitWorkTree = workTree ? path.resolve(gitTargetCwd ?? cwd, workTree) : null;
+    const cwdProtected = isProtectedWorktreeTarget(cwd, protectedBranchWorktreePaths, cwd);
+    const protectedTarget = gitWorkTree ?? gitTargetCwd;
+    const protectedCwd = protectedTarget ? isProtectedWorktreeTarget(protectedTarget, protectedBranchWorktreePaths, cwd) : cwdProtected;
+    if (!protectedCwd && (!currentBranch || !isProtectedRef(currentBranch, protectedBranches))) return null;
+    const mergeTargets = rest.filter((token) => token && !token.startsWith("-"));
+    if (mergeTargets.some((target) => isGuardianRef(target, branchPrefix, guardianBranches))) {
+      return block("manual merge of Guardian work into a protected branch is blocked; use guardian_finish", segment);
+    }
+  }
+
+  if (hasAliasCapableRuntimeConfig(configs)) {
+    const cwd = stringOption(options, "cwd") ?? process.cwd();
+    const gitTargetCwd = gitCwd ? path.resolve(cwd, gitCwd) : cwd;
+    const gitWorkTree = workTree ? path.resolve(gitTargetCwd, workTree) : null;
+    const protectedTarget = gitWorkTree ?? gitTargetCwd;
+    if (isProtectedWorktreeTarget(protectedTarget, protectedBranchWorktreePaths, cwd)) {
+      return block("runtime git alias-capable config in protected worktrees is blocked; use guardian_finish", segment);
+    }
+  }
+
+  return null;
+}

package/src/guards/shell-parser.ts

@@ -0,0 +1,126 @@
+import type { CommandSegment, MutableCommandSegment, SegmentSeparator, SegmentWithSeparator } from "./guard-types.ts";
+
+const SEGMENT_BREAK_VALUES = [";", "&&", "||", "|", "(", ")"] as const;
+export const SEGMENT_BREAKS = new Set<string>(SEGMENT_BREAK_VALUES);
+
+export function isSegmentSeparator(token: string): token is SegmentSeparator {
+  return SEGMENT_BREAKS.has(token);
+}
+
+export function tokenizeCommand(command: string): string[] {
+  const tokens: MutableCommandSegment = [];
+  let token = "";
+  let quote: "'" | "\"" | null = null;
+  let escaped = false;
+
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    const pair = `${char}${command[index + 1] ?? ""}`;
+    if (escaped) {
+      token += char;
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && quote !== "'") {
+      escaped = true;
+      continue;
+    }
+    if ((char === "'" || char === "\"") && quote === null) {
+      quote = char;
+      continue;
+    }
+    if (char === quote) {
+      quote = null;
+      continue;
+    }
+    if (quote === null && (char === "\n" || char === "\r")) {
+      if (token) tokens.push(token);
+      tokens.push(";");
+      token = "";
+      continue;
+    }
+    if (quote === null && /\s/.test(char)) {
+      if (token) tokens.push(token);
+      token = "";
+      continue;
+    }
+    if (quote === null && (pair === "&&" || pair === "||")) {
+      if (token) tokens.push(token);
+      tokens.push(pair);
+      token = "";
+      index += 1;
+      continue;
+    }
+    if (quote === null && (char === ";" || char === "|" || char === "(" || char === ")")) {
+      if (token) tokens.push(token);
+      tokens.push(char);
+      token = "";
+      continue;
+    }
+    if (quote === null && char === "$" && command[index + 1] === "(") {
+      if (token) tokens.push(token);
+      tokens.push("(");
+      token = "";
+      index += 1;
+      continue;
+    }
+    token += char;
+  }
+  if (token) tokens.push(token);
+  return tokens;
+}
+
+export function commandSegments(tokens: readonly string[]): CommandSegment[] {
+  const segments: CommandSegment[] = [];
+  let current: MutableCommandSegment = [];
+  for (const token of tokens) {
+    if (SEGMENT_BREAKS.has(token)) {
+      if (current.length) segments.push(current);
+      current = [];
+    } else {
+      current.push(token);
+    }
+  }
+  if (current.length) segments.push(current);
+  return segments;
+}
+
+export function commandSegmentsWithSeparators(tokens: readonly string[]): SegmentWithSeparator[] {
+  const segments: SegmentWithSeparator[] = [];
+  let current: MutableCommandSegment = [];
+  for (const token of tokens) {
+    if (isSegmentSeparator(token)) {
+      if (current.length) segments.push({ segment: current, nextSeparator: token });
+      current = [];
+    } else {
+      current.push(token);
+    }
+  }
+  if (current.length) segments.push({ segment: current, nextSeparator: null });
+  return segments;
+}
+
+export function findBacktickPayloads(command: string): string[] {
+  const payloads: string[] = [];
+  let escaped = false;
+  let start = -1;
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (char === "`") {
+      if (start === -1) start = index + 1;
+      else {
+        payloads.push(command.slice(start, index));
+        start = -1;
+      }
+    }
+  }
+  return payloads;
+}

package/src/guards/shell-prefix.ts

@@ -0,0 +1,100 @@
+import fs from "node:fs";
+import type { CommandPrefix, CommandSegment, MutableCommandSegment, ShellPayload } from "./guard-types.ts";
+import { normalizeForCompare } from "./path-policy.ts";
+import { tokenizeCommand } from "./shell-parser.ts";
+
+export const COMMAND_WRAPPERS = new Set(["command", "sudo", "if", "then", "do"]);
+export const SHELL_COMMANDS = new Set(["bash", "sh", "zsh", "dash", "fish"]);
+export const READ_ONLY_SHELL_COMMANDS = new Set(["pwd"]);
+
+export function stripCommandWrappers(segment: CommandSegment): CommandSegment {
+  let index = 0;
+  while (COMMAND_WRAPPERS.has(segment[index] ?? "")) index += 1;
+  if (segment[index] === "env") {
+    index += 1;
+    while (segment[index] && (/^[A-Za-z_][A-Za-z0-9_]*=.*/.test(segment[index] ?? "") || (segment[index] ?? "").startsWith("-"))) index += 1;
+  }
+  return segment.slice(index);
+}
+
+export function stripSimpleCommandWrappers(segment: CommandSegment): CommandSegment {
+  let index = 0;
+  while (COMMAND_WRAPPERS.has(segment[index] ?? "")) index += 1;
+  return segment.slice(index);
+}
+
+export function peelCommandPrefix(segment: CommandSegment): CommandPrefix {
+  let prefixed = stripSimpleCommandWrappers(segment);
+  let index = 0;
+  const assignments: string[] = [];
+  if (prefixed[index] === "env") {
+    index += 1;
+    while (prefixed[index] && (prefixed[index] ?? "").startsWith("-")) {
+      const token = prefixed[index] ?? "";
+      if (token === "-S" || token === "--split-string") {
+        const split = tokenizeCommand(prefixed[index + 1] ?? "");
+        prefixed = [...prefixed.slice(0, index), ...split, ...prefixed.slice(index + 2)];
+        continue;
+      }
+      if (token.startsWith("--split-string=")) {
+        const split = tokenizeCommand(token.slice("--split-string=".length));
+        prefixed = [...prefixed.slice(0, index), ...split, ...prefixed.slice(index + 1)];
+        continue;
+      }
+      if (token === "-u" || token === "--unset") {
+        index += 2;
+        continue;
+      }
+      if (token.startsWith("-u") || token.startsWith("--unset=")) {
+        index += 1;
+        continue;
+      }
+      index += 1;
+    }
+  }
+  while (prefixed[index] && /^[A-Za-z_][A-Za-z0-9_]*=.*/.test(prefixed[index] ?? "")) {
+    assignments.push(prefixed[index] ?? "");
+    index += 1;
+  }
+  return { stripped: prefixed.slice(index), assignments };
+}
+
+export function shellPayload(segment: CommandSegment): ShellPayload | null {
+  const { stripped, assignments } = peelCommandPrefix(segment);
+  if (!SHELL_COMMANDS.has(stripped[0] ?? "")) return null;
+  for (let index = 1; index < stripped.length; index += 1) {
+    const token = stripped[index] ?? "";
+    if (token === "-c" || token === "-lc" || token === "-cl" || /^-[a-zA-Z]*c[a-zA-Z]*$/.test(token)) {
+      const payload = stripped[index + 1] ?? "";
+      if (payload.startsWith("\"") || payload.startsWith("'")) {
+        const quote = payload[0] ?? "";
+        const payloadTokens: string[] = [];
+        for (let payloadIndex = index + 1; payloadIndex < stripped.length; payloadIndex += 1) {
+          const payloadToken = stripped[payloadIndex] ?? "";
+          payloadTokens.push(payloadToken);
+          if (payloadToken.length > 1 && payloadToken.endsWith(quote)) break;
+        }
+        return { payload: payloadTokens.join(" ").replace(new RegExp(`^\\${quote}|\\${quote}$`, "g"), ""), assignments };
+      }
+      return { payload, assignments };
+    }
+  }
+  return null;
+}
+
+export function cdTarget(segment: CommandSegment, cwd: string): string | null {
+  const stripped = stripCommandWrappers(segment);
+  if (stripped[0] !== "cd" && stripped[0] !== "pushd") return null;
+  const target = stripped.find((token, index) => index > 0 && !token.startsWith("-"));
+  if (!target || target === "-") return null;
+  const resolved = normalizeForCompare(target, cwd);
+  try {
+    return fs.statSync(resolved).isDirectory() ? resolved : null;
+  } catch {
+    return null;
+  }
+}
+
+export function mutableSegment(segment: CommandSegment): MutableCommandSegment {
+  return [...segment];
+}

package/src/guards.ts

@@ -0,0 +1,3 @@
+export { classifyNormalAgentGitCommand, classifyReadOnlyInspectionCommand } from "./guards/allowlists.ts";
+export { classifyGuardCommand, extractCommandText } from "./guards/classifier.ts";
+export { tokenizeCommand } from "./guards/shell-parser.ts";