@kontourai/flow-agents 0.1.1

package/scripts/hooks/quality-gate.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Quality Gate Hook (strict profile only)
+ *
+ * Runs per-file quality checks immediately after edits.
+ * Skips JS/TS when Biome is configured (handled by stop batch).
+ *
+ * Non-blocking — always exits 0, logs warnings to stderr.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { findProjectRoot, detectFormatter, resolveFormatterBin } = require('./lib/resolve-formatter');
+
+const MAX_STDIN = 1024 * 1024;
+
+function exec(cmd, args, cwd = process.cwd()) {
+  return spawnSync(cmd, args, { cwd, encoding: 'utf8', env: process.env, timeout: 15000 });
+}
+
+function log(msg) { process.stderr.write(`${msg}\n`); }
+
+function checkFile(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return;
+  filePath = path.resolve(filePath);
+  const ext = path.extname(filePath).toLowerCase();
+  const fix = String(process.env.SA_QUALITY_GATE_FIX || '').toLowerCase() === 'true';
+  const strict = String(process.env.SA_QUALITY_GATE_STRICT || '').toLowerCase() === 'true';
+
+  if (['.ts', '.tsx', '.js', '.jsx', '.json', '.md'].includes(ext)) {
+    const root = findProjectRoot(path.dirname(filePath));
+    const formatter = detectFormatter(root);
+    if (formatter === 'biome') {
+      if (['.ts', '.tsx', '.js', '.jsx'].includes(ext)) return; // handled by stop batch
+      const resolved = resolveFormatterBin(root, 'biome');
+      if (!resolved) return;
+      const args = [...resolved.prefix, 'check', filePath];
+      if (fix) args.push('--write');
+      const r = exec(resolved.bin, args, root);
+      if (r.status !== 0 && strict) log(`[QualityGate] Biome check failed for ${filePath}`);
+      return;
+    }
+    if (formatter === 'prettier') {
+      const resolved = resolveFormatterBin(root, 'prettier');
+      if (!resolved) return;
+      const r = exec(resolved.bin, [...resolved.prefix, fix ? '--write' : '--check', filePath], root);
+      if (r.status !== 0 && strict) log(`[QualityGate] Prettier check failed for ${filePath}`);
+      return;
+    }
+    return;
+  }
+
+  if (ext === '.go') {
+    if (fix) {
+      const r = exec('gofmt', ['-w', filePath]);
+      if (r.status !== 0 && strict) log(`[QualityGate] gofmt failed for ${filePath}`);
+    } else if (strict) {
+      const r = exec('gofmt', ['-l', filePath]);
+      if (r.stdout && r.stdout.trim()) log(`[QualityGate] gofmt check failed for ${filePath}`);
+    }
+    return;
+  }
+
+  if (ext === '.py') {
+    const args = ['format'];
+    if (!fix) args.push('--check');
+    args.push(filePath);
+    const r = exec('ruff', args);
+    if (r.status !== 0 && strict) log(`[QualityGate] Ruff check failed for ${filePath}`);
+  }
+}
+
+function run(rawInput) {
+  try {
+    const input = JSON.parse(rawInput);
+    checkFile(input.tool_input?.path || input.tool_input?.file_path || '');
+  } catch { /* ignore */ }
+  return rawInput;
+}
+
+if (require.main === module) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (raw.length < MAX_STDIN) raw += chunk.substring(0, MAX_STDIN - raw.length);
+  });
+  process.stdin.on('end', () => process.stdout.write(run(raw)));
+}
+
+module.exports = { run };

package/scripts/hooks/report-only-guard.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Report-Only Guard Hook
+ *
+ * Blocks ALL file writes. Wire this to reviewer/verifier agents
+ * that must only report findings, never modify code.
+ *
+ * Exit codes: 0 = allow, 2 = block
+ */
+
+'use strict';
+
+function run() {
+  return {
+    exitCode: 2,
+    stderr: 'BLOCKED: This agent is report-only — it cannot modify files. ' +
+      'Report findings to the orchestrator, which routes fixes back through execute-plan.',
+  };
+}
+
+module.exports = { run };

package/scripts/hooks/run-hook.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Hook runner — checks profile/disable flags before executing the actual hook.
+ *
+ * Usage:
+ *   node run-hook.js <hookId> <scriptRelativePath> [profilesCsv]
+ *
+ * Exit codes:
+ *   0 = allow (pass through)
+ *   2 = block (preToolUse only)
+ *   other = error (non-blocking)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { isHookEnabled } = require('./lib/hook-flags');
+
+const MAX_STDIN = 1024 * 1024;
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    let truncated = false;
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        const remaining = MAX_STDIN - raw.length;
+        raw += chunk.substring(0, remaining);
+        if (chunk.length > remaining) truncated = true;
+      } else {
+        truncated = true;
+      }
+    });
+    process.stdin.on('end', () => resolve({ raw, truncated }));
+    process.stdin.on('error', () => resolve({ raw, truncated }));
+  });
+}
+
+function emitHookResult(raw, output) {
+  if (typeof output === 'string' || Buffer.isBuffer(output)) {
+    process.stdout.write(String(output));
+    return 0;
+  }
+  if (output && typeof output === 'object') {
+    if (output.stderr) {
+      process.stderr.write(output.stderr.endsWith('\n') ? output.stderr : `${output.stderr}\n`);
+    }
+    if (Object.prototype.hasOwnProperty.call(output, 'stdout')) {
+      process.stdout.write(String(output.stdout ?? ''));
+    } else if (!Number.isInteger(output.exitCode) || output.exitCode === 0) {
+      process.stdout.write(raw);
+    }
+    return Number.isInteger(output.exitCode) ? output.exitCode : 0;
+  }
+  process.stdout.write(raw);
+  return 0;
+}
+
+async function main() {
+  const [, , hookId, relScriptPath, profilesCsv] = process.argv;
+  const { raw, truncated } = await readStdinRaw();
+
+  if (!hookId || !relScriptPath) {
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  if (!isHookEnabled(hookId, { profiles: profilesCsv })) {
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  const hooksDir = __dirname;
+  const scriptPath = path.resolve(hooksDir, relScriptPath);
+
+  if (!scriptPath.startsWith(hooksDir + path.sep)) {
+    process.stderr.write(`[Hook] Path traversal rejected for ${hookId}: ${scriptPath}\n`);
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  if (!fs.existsSync(scriptPath)) {
+    process.stderr.write(`[Hook] Script not found for ${hookId}: ${scriptPath}\n`);
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  // Prefer direct require() when the hook exports run() — saves ~50-100ms
+  let hookModule;
+  const src = fs.readFileSync(scriptPath, 'utf8');
+  if (/\bmodule\.exports\b/.test(src) && /\brun\b/.test(src)) {
+    try { hookModule = require(scriptPath); } catch (e) {
+      process.stderr.write(`[Hook] require() failed for ${hookId}: ${e.message}\n`);
+    }
+  }
+
+  if (hookModule && typeof hookModule.run === 'function') {
+    try {
+      const output = hookModule.run(raw, { truncated, maxStdin: MAX_STDIN });
+      process.exit(emitHookResult(raw, output));
+    } catch (e) {
+      process.stderr.write(`[Hook] run() error for ${hookId}: ${e.message}\n`);
+      process.stdout.write(raw);
+      process.exit(0);
+    }
+  }
+
+  // Legacy fallback: spawn child process
+  const result = spawnSync(process.execPath, [scriptPath], {
+    input: raw,
+    encoding: 'utf8',
+    env: { ...process.env, SA_HOOK_INPUT_TRUNCATED: truncated ? '1' : '0', SA_HOOK_INPUT_MAX_BYTES: String(MAX_STDIN) },
+    cwd: process.cwd(),
+    timeout: 30000,
+  });
+
+  if (result.stdout) process.stdout.write(result.stdout);
+  else if (Number.isInteger(result.status) && result.status === 0) process.stdout.write(raw);
+  if (result.stderr) process.stderr.write(result.stderr);
+
+  if (result.error || result.signal || result.status === null) {
+    const detail = result.error ? result.error.message : result.signal ? `signal ${result.signal}` : 'missing exit status';
+    process.stderr.write(`[Hook] legacy execution failed for ${hookId}: ${detail}\n`);
+    process.exit(1);
+  }
+
+  process.exit(Number.isInteger(result.status) ? result.status : 0);
+}
+
+main().catch(err => {
+  process.stderr.write(`[Hook] run-hook error: ${err.message}\n`);
+  process.exit(0);
+});

package/scripts/hooks/stop-format-typecheck.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * Stop Hook: Batch format + typecheck all JS/TS files edited this response
+ *
+ * Reads the accumulator from post-edit-accumulator.js, groups files by
+ * project root for formatter and by tsconfig dir for typecheck.
+ * Budget is distributed evenly across batches.
+ */
+
+'use strict';
+
+const { execFileSync, spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { findProjectRoot, detectFormatter, resolveFormatterBin } = require('./lib/resolve-formatter');
+
+const MAX_STDIN = 1024 * 1024;
+const TOTAL_BUDGET_MS = 270_000;
+
+function getAccumFile() {
+  // Import from accumulator to share session ID logic
+  try {
+    return require('./post-edit-accumulator').getAccumFile();
+  } catch {
+    const crypto = require('crypto');
+    const os = require('os');
+    const id = crypto.createHash('sha1').update(process.cwd()).digest('hex').slice(0, 12);
+    return path.join(os.tmpdir(), `flow-agents-edited-${id}.txt`);
+  }
+}
+
+function parseAccumulator(raw) {
+  return [...new Set(raw.split('\n').map(l => l.trim()).filter(Boolean))];
+}
+
+function formatBatch(projectRoot, files, timeoutMs) {
+  const formatter = detectFormatter(projectRoot);
+  if (!formatter) return;
+  const resolved = resolveFormatterBin(projectRoot, formatter);
+  if (!resolved) return;
+  const existing = files.filter(f => fs.existsSync(f));
+  if (existing.length === 0) return;
+  const args = formatter === 'biome'
+    ? [...resolved.prefix, 'check', '--write', ...existing]
+    : [...resolved.prefix, '--write', ...existing];
+  try {
+    execFileSync(resolved.bin, args, { cwd: projectRoot, stdio: ['pipe', 'pipe', 'pipe'], timeout: timeoutMs });
+  } catch { /* non-blocking */ }
+}
+
+function findTsConfigDir(filePath) {
+  let dir = path.dirname(filePath);
+  const root = path.parse(dir).root;
+  let depth = 0;
+  while (dir !== root && depth < 20) {
+    if (fs.existsSync(path.join(dir, 'tsconfig.json'))) return dir;
+    dir = path.dirname(dir);
+    depth++;
+  }
+  return null;
+}
+
+function typecheckBatch(tsConfigDir, editedFiles, timeoutMs) {
+  const args = ['tsc', '--noEmit', '--pretty', 'false'];
+  const opts = { cwd: tsConfigDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: timeoutMs };
+  let stdout = '', stderr = '', failed = false;
+  try {
+    execFileSync('npx', args, opts);
+  } catch (err) {
+    stdout = err.stdout || '';
+    stderr = err.stderr || '';
+    failed = true;
+  }
+  if (!failed) return;
+  const lines = (stdout + stderr).split('\n');
+  for (const filePath of editedFiles) {
+    const relPath = path.relative(tsConfigDir, filePath);
+    const relevant = lines
+      .filter(line => line.includes(filePath) || line.includes(relPath))
+      .slice(0, 10);
+    if (relevant.length > 0) {
+      process.stderr.write(`[Hook] TypeScript errors in ${path.basename(filePath)}:\n`);
+      relevant.forEach(l => process.stderr.write(l + '\n'));
+    }
+  }
+}
+
+function main() {
+  const accumFile = getAccumFile();
+  let raw;
+  try { raw = fs.readFileSync(accumFile, 'utf8'); } catch { return; }
+  try { fs.unlinkSync(accumFile); } catch { /* best-effort */ }
+
+  const files = parseAccumulator(raw);
+  if (files.length === 0) return;
+
+  const byRoot = new Map();
+  const byTsConfig = new Map();
+  for (const f of files) {
+    if (!/\.(ts|tsx|js|jsx)$/.test(f)) continue;
+    const resolved = path.resolve(f);
+    if (!fs.existsSync(resolved)) continue;
+    const root = findProjectRoot(path.dirname(resolved));
+    if (!byRoot.has(root)) byRoot.set(root, []);
+    byRoot.get(root).push(resolved);
+    if (/\.(ts|tsx)$/.test(f)) {
+      const tsDir = findTsConfigDir(resolved);
+      if (tsDir) {
+        if (!byTsConfig.has(tsDir)) byTsConfig.set(tsDir, []);
+        byTsConfig.get(tsDir).push(resolved);
+      }
+    }
+  }
+
+  const totalBatches = byRoot.size + byTsConfig.size;
+  const perBatch = totalBatches > 0 ? Math.floor(TOTAL_BUDGET_MS / totalBatches) : 60_000;
+
+  for (const [root, batch] of byRoot) formatBatch(root, batch, perBatch);
+  for (const [tsDir, batch] of byTsConfig) typecheckBatch(tsDir, batch, perBatch);
+}
+
+function run(rawInput) {
+  try { main(); } catch (e) {
+    process.stderr.write(`[Hook] stop-format-typecheck error: ${e.message}\n`);
+  }
+  return rawInput;
+}
+
+if (require.main === module) {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (data.length < MAX_STDIN) data += chunk.substring(0, MAX_STDIN - data.length);
+  });
+  process.stdin.on('end', () => {
+    process.stdout.write(run(data));
+    process.exit(0);
+  });
+}
+
+module.exports = { run, parseAccumulator };