plugins/ops-guards/hooks/lib/guard.mjs

Functions

Imports

It imports no other module of this repo. Imported by plugins/ops-guards/hooks/lib/heavy.mjs, plugins/ops-guards/hooks/register.js.

Source

1// Destructive-command guard (job_1e4b82452fe0, mod 3).
2//
3// Pure functions, no imports. The caller (register.js) owns every `$` call: it passes the
4// command and the session's cwd in, and runs the junction probe this file asks for.
5//
6// This reads the TEXT of a command, so it is a reminder with teeth, not a wall: the
7// mods docs say the same of their own force-push example. `bash -c "..."` and `cmd /c ...`
8// wrappers are unwrapped one level; an alias, a script file or a variable is not seen.
9
10/** Split a command into segments on ; && || | and newlines, outside quotes. */
11function segments(command) {
12  const out = [];
13  let cur = '';
14  let quote = null;
15  const flush = () => {
16    if (cur.trim()) out.push(cur.trim());
17    cur = '';
18  };
19  for (let i = 0; i < command.length; i += 1) {
20    const c = command[i];
21    if (quote) {
22      cur += c;
23      if (c === quote) quote = null;
24    } else if (c === '"' || c === "'") {
25      quote = c;
26      cur += c;
27    } else if (c === ';' || c === '\n' || c === '\r') {
28      flush();
29    } else if ((c === '&' || c === '|') && command[i + 1] === c) {
30      flush();
31      i += 1;
32    } else if (c === '|') {
33      flush();
34    } else {
35      cur += c;
36    }
37  }
38  flush();
39  return out;
40}
41
42/** Split a segment into words, honouring quotes. Backslashes are literal: Windows paths. */
43function words(segment) {
44  const out = [];
45  let cur = '';
46  let quote = null;
47  let started = false;
48  for (const c of segment) {
49    if (quote) {
50      if (c === quote) quote = null;
51      else cur += c;
52    } else if (c === '"' || c === "'") {
53      quote = c;
54      started = true;
55    } else if (/\s/.test(c)) {
56      if (started || cur) out.push(cur);
57      cur = '';
58      started = false;
59    } else {
60      cur += c;
61    }
62  }
63  if (started || cur) out.push(cur);
64  return out;
65}
66
67const SHELLS = new Set(['bash', 'sh', 'zsh', 'cmd', 'cmd.exe', 'powershell', 'powershell.exe', 'pwsh', 'pwsh.exe']);
68
69/** Every executable segment as a word list, unwrapping a shell -c string one level. */
70export function commandWords(command, depth = 0) {
71  const lists = [];
72  for (const seg of segments(command)) {
73    const w = words(seg);
74    if (w.length === 0) continue;
75    lists.push(w);
76    if (depth < 2 && SHELLS.has(w[0].toLowerCase().replace(/^.*[\\/]/, ''))) {
77      // The inner command is the longest word, which a -c / /c / -Command flag introduces.
78      const inner = [...w.slice(1)].filter((x) => /\s/.test(x)).sort((a, b) => b.length - a.length)[0];
79      if (inner) lists.push(...commandWords(inner, depth + 1));
80      else if (w.length > 2 && /^(-c|\/c|-command)$/i.test(w[1])) lists.push(w.slice(2));
81    }
82  }
83  return lists;
84}
85
86// ---- force push --------------------------------------------------------------------
87
88export const FORCE_PUSH_DENY =
89  'Force pushes are not allowed from a session. Push a new branch name instead (git push -u origin <new-branch>), ' +
90  'or have the human run the force push themselves with the ! prefix.';
91
92function gitVerb(w) {
93  if (w[0] !== 'git' && !/(^|[\\/])git(\.exe)?$/i.test(w[0])) return null;
94  let i = 1;
95  while (i < w.length && w[i].startsWith('-')) {
96    // Options that take a value before the verb.
97    i += /^-(C|c)$/.test(w[i]) || w[i] === '--git-dir' || w[i] === '--work-tree' ? 2 : 1;
98  }
99  return i < w.length ? { verb: w[i], args: w.slice(i + 1), rest: w.slice(i) } : null;
100}
101
102export function isForcePush(w) {
103  const g = gitVerb(w);
104  if (!g || g.verb !== 'push') return false;
105  return g.args.some(
106    (a) =>
107      a === '--force' ||
108      a.startsWith('--force-with-lease') ||
109      a === '--force-if-includes' ||
110      /^-[A-Za-z]*f[A-Za-z]*$/.test(a) ||
111      (a.startsWith('+') && a.length > 1)
112  );
113}
114
115// ---- git clean -x ------------------------------------------------------------------
116
117export const GIT_CLEAN_X_DENY =
118  'git clean -x / -X deletes ignored files, which includes skills/synced (local only) ' +
119  'and every node_modules. Use git clean -n to list what it would remove, and delete named untracked files individually.';
120
121export function isGitCleanIgnored(w) {
122  const g = gitVerb(w);
123  if (!g || g.verb !== 'clean') return false;
124  return g.args.some((a) => /^-[A-Za-z]*[xX][A-Za-z]*$/.test(a));
125}
126
127// ---- recursive delete of a tree that may hold a node_modules junction ----------------
128
129export const JUNCTION_DENY = (target, found) =>
130  `${target} holds a node_modules junction (${found}). A recursive delete or git worktree remove can follow the link and empty the main clone's node_modules. ` +
131  'Remove the link first, which deletes only the link: cmd /c rmdir "<worktree>\\node_modules". Then retry this command.';
132
133const RM_NAMES = new Set(['rm', 'rm.exe']);
134const RMDIR_NAMES = new Set(['rmdir', 'rd']);
135const PS_REMOVE = new Set(['remove-item', 'ri', 'rm', 'del', 'erase', 'rmdir', 'rd']);
136
137/** Turn a path the command names into an absolute Windows-style path, or null. */
138export function absolutePath(p, cwd) {
139  if (!p || /^[$%~]/.test(p)) return null;
140  let s = p;
141  const gb = /^\/([a-zA-Z])(?:\/(.*))?$/.exec(s);
142  if (gb) s = `${gb[1].toUpperCase()}:\\${gb[2] ?? ''}`;
143  s = s.replace(/\//g, '\\');
144  if (s.startsWith('\\\\')) return null;
145  if (!/^[A-Za-z]:\\/.test(s)) {
146    if (!cwd) return null;
147    s = `${cwd.replace(/[\\/]+$/, '').replace(/\//g, '\\')}\\${s}`;
148  }
149  const parts = [];
150  for (const part of s.split('\\')) {
151    if (part === '..') parts.pop();
152    else if (part !== '.' && part !== '') parts.push(part);
153  }
154  // parts[0] is the drive. A wildcard segment ends the path we can inspect.
155  const cut = parts.findIndex((x, i) => i > 0 && /[*?]/.test(x));
156  const kept = cut === -1 ? parts : parts.slice(0, cut);
157  if (kept.length === 0 || !/^[A-Za-z]:$/.test(kept[0])) return null;
158  return kept.length === 1 ? `${kept[0]}\\` : kept.join('\\');
159}
160
161/** The folders a recursive-delete segment would remove, as absolute paths. */
162export function deleteTargets(w, cwd) {
163  const name = w[0].toLowerCase().replace(/^.*[\\/]/, '');
164  let raw = [];
165  const operands = () => w.slice(1).filter((a) => !a.startsWith('-'));
166  // POSIX rm: a short cluster of at most four letters holding r or R, or --recursive.
167  const posixRecursive = w.slice(1).some((a) => a === '--recursive' || /^-[A-Za-z]{1,4}$/.test(a) && /[rR]/.test(a));
168  // PowerShell Remove-Item: -Recurse, or any prefix of it of two letters or more, with or
169  // without a value (-Recurse:$true).
170  const psRecursive = w.slice(1).some((a) => /^-re(c(u(r(se?)?)?)?)?(:.*)?$/i.test(a));
171  if (RM_NAMES.has(name) && posixRecursive) {
172    raw = operands();
173  } else if (PS_REMOVE.has(name) && psRecursive) {
174    raw = operands();
175  } else if (RMDIR_NAMES.has(name) && w.some((a) => /^\/s$/i.test(a))) {
176    raw = w.slice(1).filter((a) => !/^\/[A-Za-z]$/.test(a));
177  } else {
178    const g = gitVerb(w);
179    if (g && g.verb === 'worktree' && g.rest[1] === 'remove') {
180      const operands = g.rest.slice(2).filter((a) => !a.startsWith('-'));
181      if (operands.length) raw = [operands[operands.length - 1]];
182    }
183  }
184  return raw.map((p) => absolutePath(p, cwd)).filter(Boolean);
185}
186
187/**
188 * Judge a command. Returns { deny } for the outright refusals, and { probe: [paths] } for
189 * the recursive deletes whose targets the caller must check for a junction.
190 */
191export function analyzeCommand(command, cwd) {
192  const probe = [];
193  for (const w of commandWords(String(command ?? ''))) {
194    if (isForcePush(w)) return { deny: FORCE_PUSH_DENY };
195    if (isGitCleanIgnored(w)) return { deny: GIT_CLEAN_X_DENY };
196    for (const t of deleteTargets(w, cwd)) if (!probe.includes(t)) probe.push(t);
197  }
198  return probe.length ? { probe } : {};
199}