@imdeadpool/guardex 7.0.41 → 7.1.0

package/src/cli/commands/agents.js

@@ -0,0 +1,364 @@
+// `gx agents` — repo-scoped review + cleanup bots. Pure code-motion from
+// src/cli/main.js.
+const {
+  fs,
+  path,
+  cp,
+  TOOL_NAME,
+  AGENTS_BOTS_STATE_RELATIVE,
+} = require('../../context');
+const { resolveRepoRoot } = require('../../git');
+const { run } = require('../../core/runtime');
+const agentInspect = require('../../agents/inspect');
+const agentStatus = require('../../agents/status');
+const agentCleanupSessions = require('../../agents/cleanup-sessions');
+const agentsFinishModule = require('../../agents/finish');
+const agentsStart = require('../../agents/start');
+const { parseAgentsArgs } = require('../args');
+
+const finishAgentSession = (...callArgs) => agentsFinishModule.finishAgentSession(...callArgs);
+
+function agentsStatePathForRepo(repoRoot) {
+  return path.join(repoRoot, AGENTS_BOTS_STATE_RELATIVE);
+}
+
+function readAgentsState(repoRoot) {
+  const statePath = agentsStatePathForRepo(repoRoot);
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeAgentsState(repoRoot, state) {
+  const statePath = agentsStatePathForRepo(repoRoot);
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+
+function processAlive(pid) {
+  const normalizedPid = Number.parseInt(String(pid || ''), 10);
+  if (!Number.isInteger(normalizedPid) || normalizedPid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(normalizedPid, 0);
+  } catch (_error) {
+    return false;
+  }
+
+  const state = readProcessState(normalizedPid);
+  if (state.startsWith('Z')) {
+    return false;
+  }
+  return true;
+}
+
+function sleepSeconds(seconds) {
+  const result = run('sleep', [String(seconds)]);
+  if (Boolean(result?.error) && typeof result?.status !== 'number') {
+    throw new Error(`sleep command failed for ${seconds}s`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`sleep command failed for ${seconds}s`);
+  }
+}
+
+function readProcessCommand(pid) {
+  const result = run('ps', ['-o', 'command=', '-p', String(pid)]);
+  if ((Boolean(result?.error) && typeof result?.status !== 'number') || result.status !== 0) {
+    return '';
+  }
+  return String(result.stdout || '').trim();
+}
+
+function readProcessState(pid) {
+  const result = run('ps', ['-o', 'stat=', '-p', String(pid)]);
+  if ((Boolean(result?.error) && typeof result?.status !== 'number') || result.status !== 0) {
+    return '';
+  }
+  return String(result.stdout || '').trim();
+}
+
+function stopAgentProcessByPid(pid, expectedToken = '') {
+  const normalizedPid = Number.parseInt(String(pid || ''), 10);
+  if (!Number.isInteger(normalizedPid) || normalizedPid <= 0) {
+    return { status: 'invalid', pid: normalizedPid };
+  }
+  if (!processAlive(normalizedPid)) {
+    return { status: 'not-running', pid: normalizedPid };
+  }
+
+  if (expectedToken) {
+    const cmdline = readProcessCommand(normalizedPid);
+    if (cmdline && !cmdline.includes(expectedToken)) {
+      return { status: 'mismatch', pid: normalizedPid, command: cmdline };
+    }
+  }
+
+  try {
+    process.kill(-normalizedPid, 'SIGTERM');
+  } catch (_error) {
+    try {
+      process.kill(normalizedPid, 'SIGTERM');
+    } catch (_err) {
+      return { status: 'term-failed', pid: normalizedPid };
+    }
+  }
+
+  const deadline = Date.now() + 3_000;
+  while (Date.now() < deadline) {
+    if (!processAlive(normalizedPid)) {
+      return { status: 'stopped', pid: normalizedPid };
+    }
+    sleepSeconds(0.1);
+  }
+
+  try {
+    process.kill(-normalizedPid, 'SIGKILL');
+  } catch (_error) {
+    try {
+      process.kill(normalizedPid, 'SIGKILL');
+    } catch (_err) {
+      return { status: 'kill-failed', pid: normalizedPid };
+    }
+  }
+  sleepSeconds(0.1);
+
+  return {
+    status: processAlive(normalizedPid) ? 'kill-failed' : 'stopped',
+    pid: normalizedPid,
+  };
+}
+
+function spawnDetachedAgentProcess({ command, args, cwd, logPath }) {
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const logHandle = fs.openSync(logPath, 'a');
+  fs.writeSync(
+    logHandle,
+    `[${new Date().toISOString()}] spawn: ${command} ${args.join(' ')}\n`,
+  );
+  const child = cp.spawn(command, args, {
+    cwd,
+    detached: true,
+    stdio: ['ignore', logHandle, logHandle],
+    env: process.env,
+  });
+  fs.closeSync(logHandle);
+  if (child.error) {
+    throw child.error;
+  }
+  child.unref();
+  const pid = Number.parseInt(String(child.pid || ''), 10);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    throw new Error(`Failed to spawn detached process for ${command}`);
+  }
+  return pid;
+}
+
+function agents(rawArgs) {
+  const options = parseAgentsArgs(rawArgs);
+  if (['files', 'diff', 'locks'].includes(options.subcommand)) {
+    process.stdout.write(agentInspect.runInspectCommand(options));
+    process.exitCode = 0;
+    return;
+  }
+
+  const repoRoot = resolveRepoRoot(options.target);
+  const statePath = agentsStatePathForRepo(repoRoot);
+
+  if (options.subcommand === 'finish') {
+    const result = finishAgentSession(repoRoot, options);
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(result.evidence, null, 2)}\n`);
+    }
+    process.exitCode = 0;
+    return;
+  }
+
+  if (options.subcommand === 'cleanup-sessions') {
+    process.stdout.write(agentCleanupSessions.runCleanupSessionsCommand(repoRoot, options));
+    process.exitCode = 0;
+    return;
+  }
+
+  if (options.subcommand === 'start') {
+    if (agentsStart.shouldUseInteractivePanel(options, process.stdin, process.stdout)) {
+      agentsStart.startInteractiveAgentPanel(repoRoot, options, {
+        onDone(result) {
+          process.exitCode = result.status;
+        },
+      });
+      return;
+    }
+    if (options.dryRun) {
+      const output = agentsStart.dryRunStart(options, repoRoot);
+      process.stdout.write(output.endsWith('\n') ? output : `${output}\n`);
+      process.exitCode = 0;
+      return;
+    }
+    if (options.panel && !options.task) {
+      process.stderr.write('[gitguardex] gx agents start --panel requires an interactive terminal when no task is provided.\n');
+      process.exitCode = 1;
+      return;
+    }
+    if (options.task) {
+      const result = agentsStart.startAgentLane(repoRoot, options);
+      if (result.stdout) process.stdout.write(result.stdout);
+      if (result.stderr) process.stderr.write(result.stderr);
+      process.exitCode = result.status;
+      return;
+    }
+
+    const existingState = readAgentsState(repoRoot);
+    const existingReviewPid = Number.parseInt(String(existingState?.review?.pid || ''), 10);
+    const existingCleanupPid = Number.parseInt(String(existingState?.cleanup?.pid || ''), 10);
+    const reviewRunning = processAlive(existingReviewPid);
+    const cleanupRunning = processAlive(existingCleanupPid);
+
+    if (reviewRunning && cleanupRunning) {
+      console.log(
+        `[${TOOL_NAME}] Repo agents already running (review pid=${existingReviewPid}, cleanup pid=${existingCleanupPid}).`,
+      );
+      process.exitCode = 0;
+      return;
+    }
+
+    const reviewLogPath = path.join(repoRoot, '.omx', 'logs', 'agent-review.log');
+    const cleanupLogPath = path.join(repoRoot, '.omx', 'logs', 'agent-cleanup.log');
+
+    let reviewPid = existingReviewPid;
+    let cleanupPid = existingCleanupPid;
+    let startedAny = false;
+    let reusedAny = false;
+
+    const mainScriptPath = require.resolve('../main.js');
+    if (!reviewRunning) {
+      reviewPid = spawnDetachedAgentProcess({
+        command: process.execPath,
+        args: [
+          mainScriptPath,
+          'internal',
+          'run-shell',
+          'reviewBot',
+          '--target',
+          repoRoot,
+          '--interval',
+          String(options.reviewIntervalSeconds),
+        ],
+        cwd: repoRoot,
+        logPath: reviewLogPath,
+      });
+      startedAny = true;
+    } else {
+      reusedAny = true;
+    }
+
+    if (!cleanupRunning) {
+      cleanupPid = spawnDetachedAgentProcess({
+        command: process.execPath,
+        args: [
+          mainScriptPath,
+          'cleanup',
+          '--target',
+          repoRoot,
+          '--watch',
+          '--interval',
+          String(options.cleanupIntervalSeconds),
+          '--idle-minutes',
+          String(options.idleMinutes),
+        ],
+        cwd: repoRoot,
+        logPath: cleanupLogPath,
+      });
+      startedAny = true;
+    } else {
+      reusedAny = true;
+    }
+
+    const priorReviewInterval = Number.parseInt(String(existingState?.review?.intervalSeconds || ''), 10);
+    const priorCleanupInterval = Number.parseInt(String(existingState?.cleanup?.intervalSeconds || ''), 10);
+    const priorIdleMinutes = Number.parseInt(String(existingState?.cleanup?.idleMinutes || ''), 10);
+    const reviewIntervalSeconds = reviewRunning && Number.isInteger(priorReviewInterval) && priorReviewInterval >= 5
+      ? priorReviewInterval
+      : options.reviewIntervalSeconds;
+    const cleanupIntervalSeconds = cleanupRunning && Number.isInteger(priorCleanupInterval) && priorCleanupInterval >= 5
+      ? priorCleanupInterval
+      : options.cleanupIntervalSeconds;
+    const idleMinutes = cleanupRunning && Number.isInteger(priorIdleMinutes) && priorIdleMinutes >= 1
+      ? priorIdleMinutes
+      : options.idleMinutes;
+
+    writeAgentsState(repoRoot, {
+      schemaVersion: 1,
+      repoRoot,
+      startedAt: new Date().toISOString(),
+      review: {
+        pid: reviewPid,
+        intervalSeconds: reviewIntervalSeconds,
+        script: mainScriptPath,
+        logPath: reviewLogPath,
+      },
+      cleanup: {
+        pid: cleanupPid,
+        intervalSeconds: cleanupIntervalSeconds,
+        idleMinutes,
+        script: mainScriptPath,
+        logPath: cleanupLogPath,
+      },
+    });
+
+    console.log(
+      `[${TOOL_NAME}] Started repo agents in ${repoRoot} (review pid=${reviewPid}, cleanup pid=${cleanupPid}).`,
+    );
+    if (reusedAny && startedAny) {
+      console.log(`[${TOOL_NAME}] Reused healthy bot process(es) and started only missing ones.`);
+    }
+    console.log(`[${TOOL_NAME}] Logs: ${reviewLogPath}, ${cleanupLogPath}`);
+    process.exitCode = 0;
+    return;
+  }
+
+  if (options.subcommand === 'stop') {
+    if (options.pid) {
+      const stopResult = stopAgentProcessByPid(options.pid);
+      const success = ['stopped', 'not-running'].includes(stopResult.status);
+      console.log(
+        `[${TOOL_NAME}] Stopped agent pid ${options.pid} (${stopResult.status}).`,
+      );
+      process.exitCode = success ? 0 : 1;
+      return;
+    }
+
+    const existingState = readAgentsState(repoRoot);
+    if (!existingState) {
+      console.log(`[${TOOL_NAME}] Repo agents are not running for ${repoRoot}.`);
+      process.exitCode = 0;
+      return;
+    }
+
+    const reviewStop = stopAgentProcessByPid(existingState?.review?.pid, 'internal run-shell reviewBot');
+    const cleanupStop = stopAgentProcessByPid(existingState?.cleanup?.pid, `${path.basename(require.resolve('../main.js'))} cleanup`);
+
+    if (fs.existsSync(statePath)) {
+      fs.unlinkSync(statePath);
+    }
+
+    console.log(
+      `[${TOOL_NAME}] Stopped repo agents in ${repoRoot} (review=${reviewStop.status}, cleanup=${cleanupStop.status}).`,
+    );
+    process.exitCode = 0;
+    return;
+  }
+
+  process.stdout.write(agentStatus.runStatusCommand(repoRoot, options));
+  process.exitCode = 0;
+}
+
+module.exports = {
+  agents,
+};

package/src/cli/commands/bootstrap.js

@@ -0,0 +1,92 @@
+// Deprecated direct aliases: `install`, `fix`, `scan`. Pure code-motion from
+// src/cli/main.js — no behavior changes.
+const { TOOL_NAME } = require('../../context');
+const { parseCommonArgs } = require('../args');
+const { printOperations } = require('../../scaffold');
+const {
+  runInstallInternal,
+  runFixInternal,
+  runScanInternal,
+  printScanResult,
+  setExitCodeFromScan,
+} = require('../shared/scaffolding');
+const { assertProtectedMainWriteAllowed } = require('../shared/sandbox');
+const { describeGuardexRepoToggle } = require('../shared/repo-env');
+
+function install(rawArgs) {
+  const options = parseCommonArgs(rawArgs, {
+    target: process.cwd(),
+    force: false,
+    skipAgents: false,
+    skipPackageJson: false,
+    skipGitignore: false,
+    dryRun: false,
+    allowProtectedBaseWrite: false,
+  });
+
+  assertProtectedMainWriteAllowed(options, 'install');
+  const payload = runInstallInternal(options);
+  printOperations('Install target', payload, options.dryRun);
+
+  if (!options.dryRun) {
+    if (payload.guardexEnabled === false) {
+      console.log(
+        `[${TOOL_NAME}] Guardex is disabled for this repo (${describeGuardexRepoToggle(payload.guardexToggle)}). Skipping repo bootstrap.`,
+      );
+      process.exitCode = 0;
+      return;
+    }
+    if (!options.skipAgents) {
+      console.log(`[${TOOL_NAME}] AGENTS.md managed policy block is configured by install.`);
+    }
+    console.log(`[${TOOL_NAME}] Installed. Next step: ${TOOL_NAME} setup`);
+  }
+
+  process.exitCode = 0;
+}
+
+function fix(rawArgs) {
+  const options = parseCommonArgs(rawArgs, {
+    target: process.cwd(),
+    dropStaleLocks: true,
+    skipAgents: false,
+    skipPackageJson: false,
+    skipGitignore: false,
+    dryRun: false,
+    allowProtectedBaseWrite: false,
+  });
+
+  assertProtectedMainWriteAllowed(options, 'fix');
+  const payload = runFixInternal(options);
+  printOperations('Fix target', payload, options.dryRun);
+
+  if (!options.dryRun) {
+    if (payload.guardexEnabled === false) {
+      console.log(
+        `[${TOOL_NAME}] Guardex is disabled for this repo (${describeGuardexRepoToggle(payload.guardexToggle)}). Skipping repo repair.`,
+      );
+      process.exitCode = 0;
+      return;
+    }
+    console.log(`[${TOOL_NAME}] Repair complete. Next step: ${TOOL_NAME} scan`);
+  }
+
+  process.exitCode = 0;
+}
+
+function scan(rawArgs) {
+  const options = parseCommonArgs(rawArgs, {
+    target: process.cwd(),
+    json: false,
+  });
+
+  const result = runScanInternal(options);
+  printScanResult(result, options.json);
+  setExitCodeFromScan(result);
+}
+
+module.exports = {
+  install,
+  fix,
+  scan,
+};

package/src/cli/commands/branch.js

@@ -0,0 +1,127 @@
+// `gx branch`, `gx pivot`, `gx ship`, `gx locks`, `gx worktree` — branch
+// workflow surface. Pure code-motion from src/cli/main.js.
+const { TOOL_NAME, SHORT_TOOL_NAME } = require('../../context');
+const { resolveRepoRoot } = require('../../git');
+const {
+  run,
+  extractTargetedArgs,
+  runPackageAsset,
+  invokePackageAsset,
+} = require('../../core/runtime');
+const { finish, merge } = require('./finish');
+
+function branch(rawArgs) {
+  const activeCwd = process.cwd();
+  const [subcommand, ...rest] = rawArgs;
+  if (subcommand === 'start') {
+    const { target, passthrough } = extractTargetedArgs(rest);
+    invokePackageAsset('branchStart', passthrough, { cwd: resolveRepoRoot(target) });
+    return;
+  }
+  if (subcommand === 'finish') {
+    const { target, passthrough } = extractTargetedArgs(rest);
+    invokePackageAsset('branchFinish', passthrough, {
+      cwd: resolveRepoRoot(target),
+      env: { GUARDEX_FINISH_ACTIVE_CWD: activeCwd },
+    });
+    return;
+  }
+  if (subcommand === 'merge') return merge(rest);
+  throw new Error(
+    `Usage: ${SHORT_TOOL_NAME} branch <start|finish|merge> [options] ` +
+    `(examples: '${SHORT_TOOL_NAME} branch start "<task>" "<agent>"', '${SHORT_TOOL_NAME} branch finish --branch <agent/...>')`,
+  );
+}
+
+// `gx pivot` — single-tool-call escape from a protected branch into an isolated
+// agent worktree. AI agents (Claude Code / Codex) cannot set the bypass env
+// vars from inside a tool call, so they need a whitelisted command that does
+// the whole hop: branch+worktree creation, dirty-tree migration, and a clean
+// trailer (`WORKTREE_PATH=...`, `BRANCH=...`, `NEXT_STEP=cd ...`) the agent can
+// parse to know exactly where to `cd`.
+//
+// On an existing agent/* branch, `gx pivot` short-circuits and just prints the
+// current worktree path — safe to call as a no-op.
+function pivot(rawArgs) {
+  const { target, passthrough } = extractTargetedArgs(rawArgs);
+  const repoRoot = resolveRepoRoot(target);
+  const headProc = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoRoot });
+  const currentBranch = String(headProc.stdout || '').trim();
+  if (currentBranch.startsWith('agent/')) {
+    const wtProc = run('git', ['rev-parse', '--show-toplevel'], { cwd: repoRoot });
+    const wtPath = String(wtProc.stdout || '').trim() || repoRoot;
+    process.stdout.write(`[${TOOL_NAME} pivot] Already on agent branch '${currentBranch}'.\n`);
+    process.stdout.write(`WORKTREE_PATH=${wtPath}\n`);
+    process.stdout.write(`BRANCH=${currentBranch}\n`);
+    process.stdout.write(`NEXT_STEP=cd "${wtPath}"\n`);
+    process.exitCode = 0;
+    return;
+  }
+  const result = runPackageAsset('branchStart', passthrough, { cwd: repoRoot });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.status !== 0) {
+    process.exitCode = result.status || 1;
+    return;
+  }
+  const stdoutText = String(result.stdout || '');
+  const wtMatch = stdoutText.match(/^\[agent-branch-start\] Worktree:\s+(.+)$/m);
+  const branchMatch = stdoutText.match(/^\[agent-branch-start\] (?:Created branch|Reusing existing branch):\s+(.+)$/m);
+  if (wtMatch) {
+    const wtPath = wtMatch[1].trim();
+    process.stdout.write('\n');
+    process.stdout.write(`WORKTREE_PATH=${wtPath}\n`);
+    if (branchMatch) process.stdout.write(`BRANCH=${branchMatch[1].trim()}\n`);
+    process.stdout.write(`NEXT_STEP=cd "${wtPath}"\n`);
+  }
+  process.exitCode = 0;
+}
+
+// `gx ship` — alias for the canonical "I am done" command. Defaults to
+// `finish --via-pr --wait-for-merge --cleanup` so AI agents don't strand
+// commits or worktrees by accident. Any explicit user-supplied flags survive.
+function ship(rawArgs) {
+  const args = Array.isArray(rawArgs) ? rawArgs.slice() : [];
+  const ensureFlag = (flag) => {
+    if (!args.includes(flag)) args.push(flag);
+  };
+  ensureFlag('--via-pr');
+  ensureFlag('--wait-for-merge');
+  ensureFlag('--cleanup');
+  // `gx ship` enforces the merge gate (clean review + green CI) by default;
+  // an explicit --no-gate-review / --skip-review-gate opts back out.
+  if (!args.includes('--no-gate-review') && !args.includes('--skip-review-gate')) {
+    ensureFlag('--gate-review');
+  }
+  return finish(args);
+}
+
+function locks(rawArgs) {
+  const { target, passthrough } = extractTargetedArgs(rawArgs);
+  const result = runPackageAsset('lockTool', passthrough, { cwd: resolveRepoRoot(target) });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = result.status;
+}
+
+function worktree(rawArgs) {
+  const activeCwd = process.cwd();
+  const [subcommand, ...rest] = rawArgs;
+  if (subcommand === 'prune') {
+    const { target, passthrough } = extractTargetedArgs(rest);
+    invokePackageAsset('worktreePrune', passthrough, {
+      cwd: resolveRepoRoot(target),
+      env: { GUARDEX_PRUNE_ACTIVE_CWD: process.env.GUARDEX_PRUNE_ACTIVE_CWD || activeCwd },
+    });
+    return;
+  }
+  throw new Error(`Usage: ${SHORT_TOOL_NAME} worktree prune [cleanup-options]`);
+}
+
+module.exports = {
+  branch,
+  pivot,
+  ship,
+  locks,
+  worktree,
+};