1#!/usr/bin/env node
2/**
3 * Impeccable design hook — Cursor preToolUse write gate.
4 *
5 * Cursor's stop hook is not consistently dispatched by the headless agent, so
6 * this hook checks proposed Write/Edit content before it lands. It only denies
7 * writes when the real detector finds an issue in the proposed UI content.
8 *
9 * Contract: never break a turn accidentally. On malformed input or internal
10 * errors, allow the tool and exit 0.
11 */
12 
13import fs from 'node:fs';
14import path from 'node:path';
15 
16import {
17  ALLOWED_EXTS,
18  EDIT_COUNT_THRESHOLD,
19  GENERATED_PATH,
20  SENSITIVE_PATH,
21  appendDesignSystemNote,
22  designSystemOptions,
23  filterFindings,
24  loadDetector,
25  matchesAnyGlob,
26  persistCache,
27  readCache,
28  readConfig,
29  renderTemplate,
30  resolveProjectCwd,
31  truthy,
32  writeAuditLog,
33} from './hook-lib.mjs';
34 
35async function readStdin() {
36  if (process.stdin.isTTY) return '';
37  const chunks = [];
38  for await (const chunk of process.stdin) chunks.push(chunk);
39  return Buffer.concat(chunks).toString('utf-8');
40}
41 
42function done(payload = null) {
43  if (payload) process.stdout.write(JSON.stringify(payload));
44  process.exit(0);
45}
46 
47function allow(extra = {}, payload = {}) {
48  writeAuditLog(process.env, {
49    ts: new Date().toISOString(),
50    event: 'preToolUse',
51    ...extra,
52  });
53  return done({ permission: 'allow', ...payload });
54}
55 
56function deny(message, audit) {
57  writeAuditLog(process.env, {
58    ts: new Date().toISOString(),
59    event: 'preToolUse',
60    blocked: true,
61    ...audit,
62  });
63  return done({
64    permission: 'deny',
65    user_message: message,
66    agent_message: message,
67  });
68}
69 
70function toolInput(event) {
71  return event?.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
72}
73 
74function proposedFilePath(event, cwd) {
75  const input = toolInput(event);
76  const raw = input.file_path || input.path || input.target_file || event?.file_path;
77  const candidate = typeof raw === 'string' && raw.trim()
78    ? raw
79    : shellWriteDestination(shellCommand(input));
80  if (typeof candidate !== 'string' || !candidate.trim()) return '';
81  return path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
82}
83 
84function proposedContent(event, cwd, filePath) {
85  const input = toolInput(event);
86  for (const key of ['content', 'streamContent', 'text']) {
87    if (typeof input[key] === 'string') return input[key];
88  }
89 
90  const editProjection = projectedEditContent(input, filePath, cwd);
91  if (editProjection !== undefined) return editProjection;
92 
93  if (hasFragmentEditContent(input)) {
94    return { skipped: 'fragment-only-edit' };
95  }
96 
97  const command = shellCommand(input);
98  const pythonContent = shellPythonWriteContent(command);
99  if (pythonContent) return pythonContent;
100  const shellContent = shellHereDocContent(command);
101  if (shellContent) return shellContent;
102  const copiedContent = shellCopiedFileContent(command, cwd);
103  if (copiedContent) return copiedContent;
104  return '';
105}
106 
107function hasFragmentEditContent(input) {
108  if (!input || typeof input !== 'object') return false;
109  if (typeof input.new_string === 'string' || typeof input.newString === 'string' || typeof input.new_str === 'string' || typeof input.replacement === 'string') {
110    return true;
111  }
112  return Array.isArray(input.edits) && input.edits.some((edit) => edit && typeof edit === 'object');
113}
114 
115function projectedEditContent(input, filePath, cwd) {
116  if (!filePath) return undefined;
117  const singleOld = firstString(input, ['old_string', 'oldString', 'old_str', 'target']);
118  const singleNew = firstString(input, ['new_string', 'newString', 'new_str', 'replacement']);
119  if (singleOld !== undefined || singleNew !== undefined) {
120    if (singleOld === undefined || singleNew === undefined) return { skipped: 'fragment-only-edit' };
121    const original = readExistingProjectFile(filePath, cwd);
122    if (original === null) return { skipped: 'edit-original-unreadable' };
123    const projected = replaceOnce(original, singleOld, singleNew);
124    return projected === null ? { skipped: 'edit-old-string-missing' } : projected;
125  }
126 
127  if (!Array.isArray(input.edits)) return undefined;
128  const original = readExistingProjectFile(filePath, cwd);
129  if (original === null) return { skipped: 'edit-original-unreadable' };
130 
131  let projected = original;
132  for (const edit of input.edits) {
133    if (!edit || typeof edit !== 'object') return { skipped: 'fragment-only-edit' };
134    const oldString = firstString(edit, ['old_string', 'oldString', 'old_str', 'target']);
135    const newString = firstString(edit, ['new_string', 'newString', 'new_str', 'replacement']);
136    if (oldString === undefined || newString === undefined) return { skipped: 'fragment-only-edit' };
137    const next = replaceOnce(projected, oldString, newString);
138    if (next === null) return { skipped: 'edit-old-string-missing' };
139    projected = next;
140  }
141  return projected;
142}
143 
144function firstString(obj, keys) {
145  for (const key of keys) {
146    if (typeof obj?.[key] === 'string') return obj[key];
147  }
148  return undefined;
149}
150 
151function replaceOnce(original, oldString, newString) {
152  if (oldString === '') return null;
153  const index = original.indexOf(oldString);
154  if (index === -1) return null;
155  return `${original.slice(0, index)}${newString}${original.slice(index + oldString.length)}`;
156}
157 
158function readExistingProjectFile(filePath, cwd) {
159  if (!isInsideProject(filePath, cwd)) return null;
160  if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
161  try {
162    const stat = fs.statSync(filePath);
163    if (!stat.isFile() || stat.size > 1024 * 1024) return null;
164    return fs.readFileSync(filePath, 'utf-8');
165  } catch {
166    return null;
167  }
168}
169 
170function shellCommand(input) {
171  if (typeof input.command === 'string') return input.command;
172  if (input.args && typeof input.args.command === 'string') return input.args.command;
173  return '';
174}
175 
176function shellRedirectPath(command) {
177  if (!command || typeof command !== 'string') return '';
178  const match = command.match(/(?:^|[\s;&|])(?:>>?|1>>?)\s*(?:"([^"]+)"|'([^']+)'|([^<>\s]+))/);
179  return (match?.[1] || match?.[2] || match?.[3] || '').trim();
180}
181 
182function shellWriteDestination(command) {
183  return shellRedirectPath(command) || shellTeeDestination(command) || shellCopyPaths(command)?.dest || shellPythonWriteDestination(command) || '';
184}
185 
186function shellPythonWriteDestination(command) {
187  if (!/\bpython(?:3)?\b/.test(command || '')) return '';
188  const directPath = firstMatch(command, /(?:^|[^\w.])(?:pathlib\.)?Path\(\s*(["'])(.*?)\1\s*\)\s*\.write_text\s*\(/);
189  if (directPath) return directPath;
190 
191  const pathsByVar = new Map();
192  const assignmentRe = /\b([A-Za-z_]\w*)\s*=\s*(?:pathlib\.)?Path\(\s*(["'])(.*?)\2\s*\)/g;
193  let assignment;
194  while ((assignment = assignmentRe.exec(command))) {
195    pathsByVar.set(assignment[1], assignment[3]);
196  }
197 
198  const writeVarRe = /\b([A-Za-z_]\w*)\.write_text\s*\(/g;
199  let writeVar;
200  while ((writeVar = writeVarRe.exec(command))) {
201    const candidate = pathsByVar.get(writeVar[1]);
202    if (candidate) return candidate;
203  }
204 
205  return firstMatch(command, /\bopen\(\s*(["'])(.*?)\1\s*,\s*(["'])[wax](?:\+)?b?\3/);
206}
207 
208function firstMatch(value, re) {
209  const match = String(value || '').match(re);
210  return (match?.[2] || '').trim();
211}
212 
213function shellTeeDestination(command) {
214  const words = shellWords(command);
215  const teeIndex = words.findIndex((word) => path.basename(word) === 'tee');
216  if (teeIndex === -1) return '';
217  for (const word of words.slice(teeIndex + 1)) {
218    if (['&&', '||', ';', '|'].includes(word)) break;
219    if (word === '--') continue;
220    if (word.startsWith('-')) continue;
221    return word;
222  }
223  return '';
224}
225 
226function shellCopiedFileContent(command, cwd) {
227  const source = shellCopyPaths(command)?.source;
228  if (!source) return '';
229  const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
230  if (!isInsideProject(sourcePath, cwd)) return '';
231  if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
232  try {
233    const stat = fs.statSync(sourcePath);
234    if (!stat.isFile() || stat.size > 1024 * 1024) return '';
235    return fs.readFileSync(sourcePath, 'utf-8');
236  } catch {
237    return '';
238  }
239}
240 
241function shellCopyPaths(command) {
242  const words = shellWords(command);
243  if (words.length < 3 || path.basename(words[0]) !== 'cp') return null;
244  const args = [];
245  for (const word of words.slice(1)) {
246    if (['&&', '||', ';', '|'].includes(word)) break;
247    if (word === '--') continue;
248    if (word.startsWith('-')) continue;
249    args.push(word);
250  }
251  if (args.length < 2) return null;
252  return { source: args[args.length - 2], dest: args[args.length - 1] };
253}
254 
255function shellWords(command) {
256  if (!command || typeof command !== 'string') return [];
257  const words = [];
258  const re = /"((?:\\"|[^"])*)"|'((?:\\'|[^'])*)'|([^\s]+)/g;
259  let match;
260  while ((match = re.exec(command))) {
261    words.push((match[1] ?? match[2] ?? match[3] ?? '').replace(/\\(["'])/g, '$1'));
262  }
263  return words;
264}
265 
266function shellHereDocContent(command) {
267  if (!command || typeof command !== 'string') return '';
268  const markerMatch = command.match(/<<-?\s*['"]?([A-Za-z0-9_.-]+)['"]?[^\r\n]*\r?\n/);
269  if (!markerMatch) return '';
270  const marker = markerMatch[1];
271  const start = (markerMatch.index || 0) + markerMatch[0].length;
272  const rest = command.slice(start);
273  const endRe = new RegExp(`\\r?\\n${escapeRegExp(marker)}(?:\\r?\\n|$)`);
274  const end = rest.search(endRe);
275  return end >= 0 ? rest.slice(0, end) : '';
276}
277 
278function shellPythonWriteContent(command) {
279  if (!/\bpython(?:3)?\b/.test(command || '')) return '';
280  const script = shellHereDocContent(command) || command;
281  return pythonStringArg(script, /\.write_text\s*\(\s*/g) || pythonStringArg(script, /\.write\s*\(\s*/g);
282}
283 
284function pythonStringArg(script, prefixRe) {
285  let prefix;
286  while ((prefix = prefixRe.exec(script))) {
287    const start = prefixRe.lastIndex;
288    const triple = script.slice(start, start + 3);
289    if (triple === "'''" || triple === '"""') {
290      const end = script.indexOf(triple, start + 3);
291      if (end !== -1) return script.slice(start + 3, end);
292      continue;
293    }
294    const quote = script[start];
295    if (quote !== '"' && quote !== "'") continue;
296    let out = '';
297    for (let i = start + 1; i < script.length; i++) {
298      const ch = script[i];
299      if (ch === '\\') {
300        out += script[i + 1] || '';
301        i += 1;
302      } else if (ch === quote) {
303        return out;
304      } else {
305        out += ch;
306      }
307    }
308  }
309  return '';
310}
311 
312function escapeRegExp(value) {
313  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
314}
315 
316function relativePath(filePath, cwd) {
317  try {
318    const rel = path.relative(cwd, filePath);
319    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
320    return rel.split(path.sep).join('/');
321  } catch {
322    return filePath;
323  }
324}
325 
326function isInsideProject(filePath, cwd) {
327  try {
328    const rel = path.relative(cwd, filePath);
329    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
330  } catch {
331    return false;
332  }
333}
334 
335function cursorBlockMessage(findings, filePath, config, cwd) {
336  const rendered = renderTemplate(findings, filePath, config, { cwd });
337  const blocked = rendered.replace(
338    '[impeccable@1] Design hook findings requiring review',
339    '[impeccable@1] Impeccable design hook blocked this write before it landed. Design hook findings requiring review',
340  );
341  return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
342}
343 
344function findingSignature(findings) {
345  return findings
346    .map((finding) => `${finding.antipattern || 'unknown'}:${finding.line || 0}`)
347    .sort()
348    .join('|');
349}
350 
351function bumpCursorDenial(cache, sessionId, filePath, findings) {
352  const session = cache.sessions[sessionId] || { updatedAt: Date.now(), files: {} };
353  cache.sessions[sessionId] = session;
354  session.updatedAt = Date.now();
355  const fileEntry = session.files[filePath] || { editCount: 0, findings: [] };
356  session.files[filePath] = fileEntry;
357  const key = findingSignature(findings);
358  fileEntry.cursorDenials = fileEntry.cursorDenials && typeof fileEntry.cursorDenials === 'object'
359    ? fileEntry.cursorDenials
360    : {};
361  fileEntry.cursorDenials[key] = (fileEntry.cursorDenials[key] || 0) + 1;
362  return { key, count: fileEntry.cursorDenials[key] };
363}
364 
365async function main() {
366  if (truthy(process.env.IMPECCABLE_HOOK_DISABLED)) {
367    return allow({ skipped: 'env-disabled' });
368  }
369 
370  let event = null;
371  try {
372    const raw = await readStdin();
373    if (raw) event = JSON.parse(raw);
374  } catch {
375    return allow({ skipped: 'stdin-malformed' });
376  }
377 
378  if (!event || typeof event !== 'object') {
379    return allow({ skipped: 'stdin-empty' });
380  }
381 
382  const cwd = resolveProjectCwd(event);
383  const started = Date.now();
384  const filePath = proposedFilePath(event, cwd);
385  const audit = {
386    harness: 'cursor',
387    cwd,
388    tool: event.tool_name || null,
389    file: filePath || null,
390  };
391 
392  if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
393  if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
394  if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
395  if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
396 
397  const ext = path.extname(filePath).toLowerCase();
398  audit.ext = ext;
399  if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
400 
401  const contentResult = proposedContent(event, cwd, filePath);
402  if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
403    return allow({ ...audit, skipped: contentResult.skipped, durationMs: Date.now() - started });
404  }
405  const content = typeof contentResult === 'string' ? contentResult : '';
406  if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
407 
408  const config = readConfig(cwd);
409  if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
410 
411  const rel = relativePath(filePath, cwd);
412  if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
413    return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
414  }
415 
416  const detector = await loadDetector();
417  if (!detector || typeof detector.detectText !== 'function') {
418    return allow({ ...audit, skipped: 'detector-missing', durationMs: Date.now() - started });
419  }
420  const scanOptions = designSystemOptions(config, detector, cwd);
421 
422  let findings = [];
423  try {
424    findings = await detector.detectText(content, filePath, scanOptions);
425  } catch {
426    return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
427  }
428 
429  const filtered = filterFindings(findings || [], content, ext, config);
430  if (filtered.length === 0) {
431    return allow({
432      ...audit,
433      findings: (findings || []).length,
434      blockedFindings: 0,
435      durationMs: Date.now() - started,
436    });
437  }
438 
439  const message = appendDesignSystemNote(cursorBlockMessage(filtered, filePath, config, cwd), scanOptions);
440  const sessionId = event.session_id || event.conversation_id || 'unknown';
441  const cache = readCache(cwd);
442  const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
443  persistCache(cwd, cache);
444  if (denial.count > EDIT_COUNT_THRESHOLD) {
445    const warning = `${message}\n\nThis is the ${denial.count}th repeated denial for the same file and finding signature, so Impeccable is allowing this write to avoid a loop. Reconsider the issue immediately after the tool runs.`;
446    return allow({
447      ...audit,
448      findings: (findings || []).length,
449      blockedFindings: filtered.length,
450      cursorDenialKey: denial.key,
451      cursorDenialCount: denial.count,
452      downgraded: true,
453      chars: warning.length,
454      durationMs: Date.now() - started,
455    }, {
456      user_message: warning,
457      agent_message: warning,
458    });
459  }
460  return deny(message, {
461    ...audit,
462    findings: (findings || []).length,
463    blockedFindings: filtered.length,
464    cursorDenialKey: denial.key,
465    cursorDenialCount: denial.count,
466    chars: message.length,
467    durationMs: Date.now() - started,
468  });
469}
470 
471main().catch((err) => {
472  if (process.env.IMPECCABLE_HOOK_DEBUG) {
473    process.stderr.write(`[impeccable-hook-before-edit] ${err}\n`);
474  }
475  done({ permission: 'allow' });
476});
477