@imdeadpool/guardex 7.0.19 → 7.0.21

package/src/output/index.js

@@ -0,0 +1,398 @@
+const {
+  path,
+  packageJson,
+  TOOL_NAME,
+  SHORT_TOOL_NAME,
+  LEGACY_NAMES,
+  GUARDEX_REPO_TOGGLE_ENV,
+  CLI_COMMAND_DESCRIPTIONS,
+  AGENT_BOT_DESCRIPTIONS,
+  DOCTOR_AUTO_FINISH_DETAIL_LIMIT,
+  DOCTOR_AUTO_FINISH_BRANCH_LABEL_MAX,
+  DOCTOR_AUTO_FINISH_MESSAGE_MAX,
+} = require('../context');
+
+function runtimeVersion() {
+  return `${packageJson.name}/${packageJson.version} ${process.platform}-${process.arch} node-${process.version}`;
+}
+
+function supportsAnsiColors() {
+  const forced = String(process.env.FORCE_COLOR || '').trim().toLowerCase();
+  if (['0', 'false', 'no', 'off'].includes(forced)) {
+    return false;
+  }
+  if (forced.length > 0) {
+    return true;
+  }
+  if (process.env.NO_COLOR) {
+    return false;
+  }
+  return Boolean(process.stdout.isTTY) && process.env.TERM !== 'dumb';
+}
+
+function colorize(text, colorCode) {
+  if (!supportsAnsiColors()) {
+    return text;
+  }
+  return `\u001B[${colorCode}m${text}\u001B[0m`;
+}
+
+function doctorOutputColorCode(status) {
+  const normalized = String(status || '').trim().toLowerCase();
+  if (['active', 'done', 'ok', 'safe', 'success'].includes(normalized)) {
+    return '32';
+  }
+  if (normalized === 'disabled') {
+    return '36';
+  }
+  if (['degraded', 'pending', 'skip', 'warn', 'warning'].includes(normalized)) {
+    return '33';
+  }
+  if (['error', 'fail', 'inactive', 'unsafe'].includes(normalized)) {
+    return '31';
+  }
+  return null;
+}
+
+function colorizeDoctorOutput(text, status) {
+  const colorCode = doctorOutputColorCode(status);
+  return colorCode ? colorize(text, colorCode) : text;
+}
+
+function detectAutoFinishDetailStatus(detail) {
+  const trimmed = String(detail || '').trim();
+  const match = trimmed.match(/^\[(\w+)\]/);
+  if (match) {
+    return match[1].toLowerCase();
+  }
+  if (/^Skipped\b/i.test(trimmed) || /^No local agent branches found\b/i.test(trimmed)) {
+    return 'skip';
+  }
+  return null;
+}
+
+function detectAutoFinishSummaryStatus(summary) {
+  if (!summary || summary.enabled === false) {
+    return detectAutoFinishDetailStatus(summary?.details?.[0]);
+  }
+  if ((summary.failed || 0) > 0) {
+    return 'fail';
+  }
+  if ((summary.completed || 0) > 0) {
+    return 'done';
+  }
+  if ((summary.skipped || 0) > 0) {
+    return 'skip';
+  }
+  return null;
+}
+
+function statusDot(status) {
+  if (status === 'active') {
+    return colorize('●', '32');
+  }
+  if (status === 'inactive') {
+    return colorize('●', '31');
+  }
+  if (status === 'disabled') {
+    return colorize('●', '36');
+  }
+  return colorize('●', '33');
+}
+
+function commandCatalogLines(indent = '  ') {
+  const maxCommandLength = CLI_COMMAND_DESCRIPTIONS.reduce(
+    (max, [command]) => Math.max(max, command.length),
+    0,
+  );
+  return CLI_COMMAND_DESCRIPTIONS.map(
+    ([command, description]) => `${indent}${command.padEnd(maxCommandLength + 2)}${description}`,
+  );
+}
+
+function agentBotCatalogLines(indent = '  ') {
+  const maxCommandLength = AGENT_BOT_DESCRIPTIONS.reduce(
+    (max, [command]) => Math.max(max, command.length),
+    0,
+  );
+  return AGENT_BOT_DESCRIPTIONS.map(
+    ([command, description]) => `${indent}${command.padEnd(maxCommandLength + 2)}${description}`,
+  );
+}
+
+function repoToggleLines(indent = '  ') {
+  return [
+    `${indent}Set repo-root .env: ${GUARDEX_REPO_TOGGLE_ENV}=0 disables Guardex, ${GUARDEX_REPO_TOGGLE_ENV}=1 enables it again`,
+  ];
+}
+
+function printToolLogsSummary() {
+  const usageLine = `    $ ${SHORT_TOOL_NAME} <command> [options]`;
+  const commandDetails = commandCatalogLines('    ');
+  const agentBotDetails = agentBotCatalogLines('    ');
+  const repoToggleDetails = repoToggleLines('    ');
+
+  if (!supportsAnsiColors()) {
+    console.log(`${TOOL_NAME}-tools logs:`);
+    console.log('  USAGE');
+    console.log(usageLine);
+    console.log('  COMMANDS');
+    for (const line of commandDetails) {
+      console.log(line);
+    }
+    console.log('  AGENT BOT');
+    for (const line of agentBotDetails) {
+      console.log(line);
+    }
+    console.log('  REPO TOGGLE');
+    for (const line of repoToggleDetails) {
+      console.log(line);
+    }
+    return;
+  }
+
+  const title = colorize(`${TOOL_NAME}-tools logs`, '1;36');
+  const usageHeader = colorize('USAGE', '1');
+  const commandsHeader = colorize('COMMANDS', '1');
+  const agentBotHeader = colorize('AGENT BOT', '1');
+  const repoToggleHeader = colorize('REPO TOGGLE', '1');
+  const pipe = colorize('│', '90');
+  const tee = colorize('├', '90');
+  const corner = colorize('└', '90');
+
+  console.log(`${title}:`);
+  console.log(`  ${tee}─ ${usageHeader}`);
+  console.log(`  ${pipe}${usageLine}`);
+  console.log(`  ${tee}─ ${commandsHeader}`);
+  for (const line of commandDetails) {
+    if (!line) {
+      console.log(`  ${pipe}`);
+      continue;
+    }
+    console.log(`  ${pipe}${line.slice(2)}`);
+  }
+  console.log(`  ${tee}─ ${agentBotHeader}`);
+  for (const line of agentBotDetails) {
+    if (!line) {
+      console.log(`  ${pipe}`);
+      continue;
+    }
+    console.log(`  ${pipe}${line.slice(2)}`);
+  }
+  console.log(`  ${tee}─ ${repoToggleHeader}`);
+  for (const line of repoToggleDetails) {
+    if (!line) {
+      console.log(`  ${pipe}`);
+      continue;
+    }
+    console.log(`  ${pipe}${line.slice(2)}`);
+  }
+  console.log(`  ${corner}─ ${colorize(`Try '${TOOL_NAME} doctor' for one-step repair + verification.`, '2')}`);
+}
+
+function usage(options = {}) {
+  const { outsideGitRepo = false } = options;
+
+  console.log(`A command-line tool that sets up hardened multi-agent safety for git repositories.
+
+VERSION
+  ${runtimeVersion()}
+
+USAGE
+  $ ${SHORT_TOOL_NAME} <command> [options]
+
+COMMANDS
+${commandCatalogLines().join('\n')}
+
+AGENT BOT
+${agentBotCatalogLines().join('\n')}
+
+REPO TOGGLE
+${repoToggleLines().join('\n')}
+
+NOTES
+  - No command = ${SHORT_TOOL_NAME} status. ${SHORT_TOOL_NAME} init is an alias of ${SHORT_TOOL_NAME} setup.
+  - Global installs need Y/N approval; GitHub CLI (gh) is required for PR automation.
+  - Target another repo: ${SHORT_TOOL_NAME} <cmd> --target <repo-path>.
+  - On protected main, setup/install/fix/doctor auto-sandbox via agent branch + PR flow.
+  - Run '${SHORT_TOOL_NAME} cleanup' to prune merged agent branches/worktrees.
+  - Legacy aliases: ${LEGACY_NAMES.join(', ')}.`);
+
+  if (outsideGitRepo) {
+    console.log(`
+[${TOOL_NAME}] No git repository detected in current directory.
+[${TOOL_NAME}] Start from a repo root, or pass an explicit target:
+  ${TOOL_NAME} setup --target <path-to-git-repo>
+  ${TOOL_NAME} doctor --target <path-to-git-repo>`);
+  }
+}
+
+function formatElapsedDuration(ms) {
+  const durationMs = Number.isFinite(ms) ? Math.max(0, ms) : 0;
+  if (durationMs < 1000) {
+    return `${Math.round(durationMs)}ms`;
+  }
+  if (durationMs < 10_000) {
+    return `${(durationMs / 1000).toFixed(1)}s`;
+  }
+  return `${Math.round(durationMs / 1000)}s`;
+}
+
+function truncateMiddle(value, maxLength) {
+  const text = String(value || '');
+  const limit = Number.isFinite(maxLength) ? Math.max(4, maxLength) : 0;
+  if (!limit || text.length <= limit) {
+    return text;
+  }
+
+  const visible = limit - 1;
+  const headLength = Math.ceil(visible / 2);
+  const tailLength = Math.floor(visible / 2);
+  return `${text.slice(0, headLength)}…${text.slice(text.length - tailLength)}`;
+}
+
+function truncateTail(value, maxLength) {
+  const text = String(value || '');
+  const limit = Number.isFinite(maxLength) ? Math.max(4, maxLength) : 0;
+  if (!limit || text.length <= limit) {
+    return text;
+  }
+  return `${text.slice(0, limit - 1)}…`;
+}
+
+function compactAutoFinishPathSegments(message) {
+  return String(message || '').replace(/\((\/[^)]+)\)/g, (_, rawPath) => {
+    if (
+      rawPath.includes(`${path.sep}.omx${path.sep}agent-worktrees${path.sep}`) ||
+      rawPath.includes(`${path.sep}.omc${path.sep}agent-worktrees${path.sep}`)
+    ) {
+      return `(${path.basename(rawPath)})`;
+    }
+    return `(${truncateMiddle(rawPath, 72)})`;
+  });
+}
+
+function detectRecoverableAutoFinishConflict(message) {
+  const text = String(message || '').trim();
+  if (!text) {
+    return null;
+  }
+
+  if (/rebase --continue/i.test(text) && /rebase --abort/i.test(text)) {
+    return {
+      rawLabel: 'auto-finish requires manual rebase.',
+      summary: 'manual rebase required in the source-probe worktree; run rebase --continue or rebase --abort',
+    };
+  }
+
+  if (/Rebase\/merge '.+' into '.+' and resolve conflicts before finishing\./i.test(text)) {
+    return {
+      rawLabel: 'auto-finish requires manual rebase or merge.',
+      summary: 'manual rebase or merge required before auto-finish can continue',
+    };
+  }
+
+  if (/Merge conflict detected while merging/i.test(text)) {
+    return {
+      rawLabel: 'auto-finish requires manual merge resolution.',
+      summary: 'manual merge resolution required before auto-finish can continue',
+    };
+  }
+
+  return null;
+}
+
+function summarizeAutoFinishDetail(detail) {
+  const trimmed = String(detail || '').trim();
+  const match = trimmed.match(/^\[(\w+)\]\s+([^:]+):\s*(.*)$/);
+  if (!match) {
+    return truncateTail(compactAutoFinishPathSegments(trimmed), DOCTOR_AUTO_FINISH_MESSAGE_MAX);
+  }
+
+  const [, status, rawBranch, rawMessage] = match;
+  const branch = truncateMiddle(rawBranch, DOCTOR_AUTO_FINISH_BRANCH_LABEL_MAX);
+  let message = String(rawMessage || '').trim();
+  const recoverableConflict = status === 'skip' ? detectRecoverableAutoFinishConflict(message) : null;
+
+  if (recoverableConflict) {
+    message = recoverableConflict.summary;
+  } else if (status === 'fail') {
+    message = message.replace(/^auto-finish failed\.?\s*/i, '');
+    if (/\[agent-sync-guard\]/.test(message) && /Resolve conflicts/i.test(message)) {
+      message = 'rebase conflict in finish flow; run rebase --continue or rebase --abort in the source-probe worktree';
+    } else if (/unable to compute ahead\/behind/i.test(message)) {
+      const aheadBehindMatch = message.match(/unable to compute ahead\/behind(?: \([^)]+\))?/i);
+      if (aheadBehindMatch) {
+        message = aheadBehindMatch[0];
+      }
+    } else if (/remote ref does not exist/i.test(message)) {
+      message = 'branch merged, but the remote ref was already removed during cleanup';
+    }
+  }
+
+  message = compactAutoFinishPathSegments(message)
+    .replace(/\s+\|\s+/g, '; ')
+    .trim();
+
+  return `[${status}] ${branch}: ${truncateTail(message, DOCTOR_AUTO_FINISH_MESSAGE_MAX)}`;
+}
+
+function printAutoFinishSummary(summary, options = {}) {
+  const enabled = Boolean(summary && summary.enabled);
+  const details = Array.isArray(summary && summary.details) ? summary.details : [];
+  const baseBranch = String(options.baseBranch || summary?.baseBranch || '').trim();
+  const verbose = Boolean(options.verbose);
+  const detailLimit = Number.isFinite(options.detailLimit)
+    ? Math.max(0, options.detailLimit)
+    : DOCTOR_AUTO_FINISH_DETAIL_LIMIT;
+
+  if (enabled) {
+    console.log(
+      colorizeDoctorOutput(
+        `[${TOOL_NAME}] Auto-finish sweep (base=${baseBranch}): attempted=${summary.attempted}, completed=${summary.completed}, skipped=${summary.skipped}, failed=${summary.failed}`,
+        detectAutoFinishSummaryStatus(summary),
+      ),
+    );
+    const visibleDetails = verbose ? details : details.slice(0, detailLimit).map(summarizeAutoFinishDetail);
+    for (const detail of visibleDetails) {
+      console.log(colorizeDoctorOutput(`[${TOOL_NAME}]   ${detail}`, detectAutoFinishDetailStatus(detail)));
+    }
+    if (!verbose && details.length > visibleDetails.length) {
+      console.log(
+        colorizeDoctorOutput(
+          `[${TOOL_NAME}]   … ${details.length - visibleDetails.length} more branch result(s). Re-run with --verbose-auto-finish for full details.`,
+          'warn',
+        ),
+      );
+    }
+    return;
+  }
+
+  if (details.length > 0) {
+    const detail = verbose ? details[0] : summarizeAutoFinishDetail(details[0]);
+    console.log(colorizeDoctorOutput(`[${TOOL_NAME}] ${detail}`, detectAutoFinishDetailStatus(detail)));
+  }
+}
+
+module.exports = {
+  runtimeVersion,
+  supportsAnsiColors,
+  colorize,
+  doctorOutputColorCode,
+  colorizeDoctorOutput,
+  detectAutoFinishDetailStatus,
+  detectAutoFinishSummaryStatus,
+  statusDot,
+  commandCatalogLines,
+  agentBotCatalogLines,
+  repoToggleLines,
+  printToolLogsSummary,
+  usage,
+  formatElapsedDuration,
+  truncateMiddle,
+  truncateTail,
+  compactAutoFinishPathSegments,
+  detectRecoverableAutoFinishConflict,
+  summarizeAutoFinishDetail,
+  printAutoFinishSummary,
+};

package/src/sandbox/index.js

@@ -0,0 +1,68 @@
+function createSandboxApi(deps) {
+  const {
+    protectedBaseWriteBlock,
+    runInstallInternal,
+    ensureSetupProtectedBranches,
+    ensureParentWorkspaceView,
+    buildParentWorkspaceView,
+    runFixInternal,
+  } = deps;
+
+  function assertProtectedMainWriteAllowed(options, commandName) {
+    const blocked = protectedBaseWriteBlock(options);
+    if (!blocked) {
+      return;
+    }
+
+    throw new Error(
+      `${commandName} blocked on protected branch '${blocked.branch}' in an initialized repo.\n` +
+      `Keep local '${blocked.branch}' pull-only: start an agent branch/worktree first:\n` +
+      `  gx branch start "<task>" "codex"\n` +
+      `Override once only when intentional: --allow-protected-base-write`,
+    );
+  }
+
+  function runSetupBootstrapInternal(options) {
+    const installPayload = runInstallInternal(options);
+    installPayload.operations.push(
+      ensureSetupProtectedBranches(installPayload.repoRoot, Boolean(options.dryRun)),
+    );
+
+    let parentWorkspace = null;
+    if (options.parentWorkspaceView) {
+      installPayload.operations.push(
+        ensureParentWorkspaceView(installPayload.repoRoot, Boolean(options.dryRun)),
+      );
+      if (!options.dryRun) {
+        parentWorkspace = buildParentWorkspaceView(installPayload.repoRoot);
+      }
+    }
+
+    const fixPayload = runFixInternal({
+      target: installPayload.repoRoot,
+      dryRun: options.dryRun,
+      force: options.force,
+      forceManagedPaths: options.forceManagedPaths,
+      dropStaleLocks: true,
+      skipAgents: options.skipAgents,
+      skipPackageJson: options.skipPackageJson,
+      skipGitignore: options.skipGitignore,
+      allowProtectedBaseWrite: options.allowProtectedBaseWrite,
+    });
+
+    return {
+      installPayload,
+      fixPayload,
+      parentWorkspace,
+    };
+  }
+
+  return {
+    assertProtectedMainWriteAllowed,
+    runSetupBootstrapInternal,
+  };
+}
+
+module.exports = {
+  createSandboxApi,
+};

package/src/scaffold/index.js

@@ -0,0 +1,148 @@
+const {
+  fs,
+  path,
+  TOOL_NAME,
+  SHORT_TOOL_NAME,
+  toDestinationPath,
+  EXECUTABLE_RELATIVE_PATHS,
+  CRITICAL_GUARDRAIL_PATHS,
+} = require('../context');
+
+function ensureParentDir(repoRoot, filePath, dryRun) {
+  if (dryRun) return;
+
+  const parentDir = path.dirname(filePath);
+  const relativeParentDir = path.relative(repoRoot, parentDir);
+  const segments = relativeParentDir.split(path.sep).filter(Boolean);
+  let currentPath = repoRoot;
+
+  for (const segment of segments) {
+    currentPath = path.join(currentPath, segment);
+    if (fs.existsSync(currentPath) && !fs.statSync(currentPath).isDirectory()) {
+      const blockingPath = path.relative(repoRoot, currentPath) || path.basename(currentPath);
+      const targetPath = path.relative(repoRoot, filePath) || path.basename(filePath);
+      throw new Error(
+        `Path conflict: ${blockingPath} exists as a file, but ${targetPath} needs it to be a directory. ` +
+        `Remove or rename ${blockingPath} and rerun '${SHORT_TOOL_NAME} setup'.`,
+      );
+    }
+  }
+
+  fs.mkdirSync(parentDir, { recursive: true });
+}
+
+function ensureExecutable(destinationPath, relativePath, dryRun) {
+  if (dryRun) return;
+  if (EXECUTABLE_RELATIVE_PATHS.has(relativePath)) {
+    fs.chmodSync(destinationPath, 0o755);
+  }
+}
+
+function isCriticalGuardrailPath(relativePath) {
+  return CRITICAL_GUARDRAIL_PATHS.has(relativePath);
+}
+
+function shellSingleQuote(value) {
+  return `'${String(value).replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function renderShellDispatchShim(commandParts) {
+  const rendered = commandParts.map((part) => shellSingleQuote(part)).join(' ');
+  return (
+    '#!/usr/bin/env bash\n' +
+    'set -euo pipefail\n' +
+    '\n' +
+    'if [[ -n "${GUARDEX_CLI_ENTRY:-}" ]]; then\n' +
+    '  node_bin="${GUARDEX_NODE_BIN:-node}"\n' +
+    `  exec "$node_bin" "$GUARDEX_CLI_ENTRY" ${rendered} "$@"\n` +
+    'fi\n' +
+    '\n' +
+    'resolve_guardex_cli() {\n' +
+    '  if [[ -n "${GUARDEX_CLI_BIN:-}" ]]; then\n' +
+    '    printf \'%s\' "$GUARDEX_CLI_BIN"\n' +
+    '    return 0\n' +
+    '  fi\n' +
+    '  if command -v gx >/dev/null 2>&1; then\n' +
+    '    printf \'%s\' "gx"\n' +
+    '    return 0\n' +
+    '  fi\n' +
+    '  if command -v gitguardex >/dev/null 2>&1; then\n' +
+    '    printf \'%s\' "gitguardex"\n' +
+    '    return 0\n' +
+    '  fi\n' +
+    '  echo "[gitguardex-shim] Missing gx CLI in PATH." >&2\n' +
+    '  exit 1\n' +
+    '}\n' +
+    '\n' +
+    'cli_bin="$(resolve_guardex_cli)"\n' +
+    `exec "$cli_bin" ${rendered} "$@"\n`
+  );
+}
+
+function renderPythonDispatchShim(commandParts) {
+  return (
+    '#!/usr/bin/env python3\n' +
+    'import os\n' +
+    'import shutil\n' +
+    'import subprocess\n' +
+    'import sys\n' +
+    '\n' +
+    `COMMAND = ${JSON.stringify(commandParts)}\n` +
+    '\n' +
+    'entry = os.environ.get("GUARDEX_CLI_ENTRY")\n' +
+    'if entry:\n' +
+    '    node_bin = os.environ.get("GUARDEX_NODE_BIN") or shutil.which("node") or "node"\n' +
+    '    raise SystemExit(subprocess.call([node_bin, entry, *COMMAND, *sys.argv[1:]]))\n' +
+    'cli = os.environ.get("GUARDEX_CLI_BIN") or shutil.which("gx") or shutil.which("gitguardex")\n' +
+    'if not cli:\n' +
+    '    sys.stderr.write("[gitguardex-shim] Missing gx CLI in PATH.\\n")\n' +
+    '    raise SystemExit(1)\n' +
+    'raise SystemExit(subprocess.call([cli, *COMMAND, *sys.argv[1:]]))\n'
+  );
+}
+
+function managedForceConflictMessage(relativePath) {
+  return (
+    `Refusing to overwrite existing file without --force: ${relativePath}\n` +
+    `Use '--force ${relativePath}' to rewrite only this managed file, or '--force' to rewrite all managed files.`
+  );
+}
+
+function printOperations(title, payload, dryRun = false) {
+  console.log(`[${TOOL_NAME}] ${title}: ${payload.repoRoot}`);
+  for (const operation of payload.operations) {
+    const note = operation.note ? ` (${operation.note})` : '';
+    console.log(`  - ${operation.status.padEnd(12)} ${operation.file}${note}`);
+  }
+  console.log(
+    `  - hooksPath    ${payload.hookResult.status} ${payload.hookResult.key}=${payload.hookResult.value}`,
+  );
+
+  if (dryRun) {
+    console.log(`[${TOOL_NAME}] Dry run complete. No files were modified.`);
+  }
+}
+
+function printStandaloneOperations(title, rootLabel, operations, dryRun = false) {
+  console.log(`[${TOOL_NAME}] ${title}: ${rootLabel}`);
+  for (const operation of operations) {
+    const note = operation.note ? ` (${operation.note})` : '';
+    console.log(`  - ${operation.status.padEnd(12)} ${operation.file}${note}`);
+  }
+  if (dryRun) {
+    console.log(`[${TOOL_NAME}] Dry run complete. No files were modified.`);
+  }
+}
+
+module.exports = {
+  toDestinationPath,
+  ensureParentDir,
+  ensureExecutable,
+  isCriticalGuardrailPath,
+  shellSingleQuote,
+  renderShellDispatchShim,
+  renderPythonDispatchShim,
+  managedForceConflictMessage,
+  printOperations,
+  printStandaloneOperations,
+};