@imdeadpool/guardex 7.0.41 → 7.1.0

package/src/ci-init/index.js

@@ -0,0 +1,265 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const cp = require('node:child_process');
+
+const { TEMPLATE_FILES, toDestinationPath, TEMPLATE_ROOT, PACKAGE_ROOT } = require('../context');
+
+const TOOL_NAME = 'gx';
+
+const WORKFLOW_TEMPLATE_PREFIX = 'github/workflows/';
+
+function listWorkflowTemplates() {
+  return TEMPLATE_FILES.filter((entry) => entry.startsWith(WORKFLOW_TEMPLATE_PREFIX));
+}
+
+function resolveTemplateSource(relativeTemplatePath) {
+  const localTemplate = path.join(TEMPLATE_ROOT, relativeTemplatePath);
+  if (fs.existsSync(localTemplate)) return localTemplate;
+  const packageTemplate = path.join(PACKAGE_ROOT, 'templates', relativeTemplatePath);
+  if (fs.existsSync(packageTemplate)) return packageTemplate;
+  return null;
+}
+
+function copyFileEnsuringDir(sourcePath, destinationAbsolute) {
+  fs.mkdirSync(path.dirname(destinationAbsolute), { recursive: true });
+  fs.copyFileSync(sourcePath, destinationAbsolute);
+}
+
+function shouldCopy(destinationAbsolute, options) {
+  if (!fs.existsSync(destinationAbsolute)) return { copy: true, reason: 'create' };
+  if (options.force) return { copy: true, reason: 'overwrite' };
+  return { copy: false, reason: 'exists' };
+}
+
+function planCiInitOperations(options) {
+  const targetRoot = path.resolve(options.target || process.cwd());
+  const operations = [];
+  for (const templateRelative of listWorkflowTemplates()) {
+    const destinationRelative = toDestinationPath(templateRelative);
+    const destinationAbsolute = path.join(targetRoot, destinationRelative);
+    const sourcePath = resolveTemplateSource(templateRelative);
+    if (!sourcePath) {
+      operations.push({
+        template: templateRelative,
+        destination: destinationRelative,
+        status: 'missing-source',
+      });
+      continue;
+    }
+    const decision = shouldCopy(destinationAbsolute, options);
+    operations.push({
+      template: templateRelative,
+      source: sourcePath,
+      destination: destinationRelative,
+      destinationAbsolute,
+      status: decision.copy ? decision.reason : 'skipped',
+    });
+  }
+  return { targetRoot, operations };
+}
+
+function performCiInitOperations(operations, { dryRun }) {
+  const summary = { copied: [], overwritten: [], skipped: [], missing: [] };
+  for (const op of operations) {
+    if (op.status === 'missing-source') {
+      summary.missing.push(op.template);
+      continue;
+    }
+    if (op.status === 'skipped') {
+      summary.skipped.push(op.destination);
+      continue;
+    }
+    if (!dryRun) {
+      copyFileEnsuringDir(op.source, op.destinationAbsolute);
+    }
+    if (op.status === 'overwrite') {
+      summary.overwritten.push(op.destination);
+    } else {
+      summary.copied.push(op.destination);
+    }
+  }
+  return summary;
+}
+
+function maybeStageOnAgentBranch(targetRoot, summary, options) {
+  if (options.dryRun || options.noStage) return null;
+  if (!summary.copied.length && !summary.overwritten.length) return null;
+  // Best-effort stage: only when the target is itself a git repo. Failures
+  // are non-fatal — the user can always `git add` themselves.
+  const isGit = cp.spawnSync('git', ['-C', targetRoot, 'rev-parse', '--is-inside-work-tree'], {
+    encoding: 'utf8',
+  });
+  if (isGit.status !== 0) return { staged: false, reason: 'target is not a git repo' };
+  const files = [...summary.copied, ...summary.overwritten];
+  const add = cp.spawnSync('git', ['-C', targetRoot, 'add', '--', ...files], { encoding: 'utf8' });
+  if (add.status !== 0) {
+    return { staged: false, reason: (add.stderr || add.stdout || '').trim() };
+  }
+  return { staged: true, count: files.length };
+}
+
+function formatCiInitReport({ targetRoot, summary, stageResult, dryRun }) {
+  const lines = [];
+  const mode = dryRun ? 'dry-run' : 'apply';
+  lines.push(`${TOOL_NAME} ci-init (${mode}) — target: ${targetRoot}`);
+  if (summary.copied.length) {
+    lines.push(`  created (${summary.copied.length}):`);
+    for (const file of summary.copied) lines.push(`    + ${file}`);
+  }
+  if (summary.overwritten.length) {
+    lines.push(`  overwritten (${summary.overwritten.length}):`);
+    for (const file of summary.overwritten) lines.push(`    ~ ${file}`);
+  }
+  if (summary.skipped.length) {
+    lines.push(`  skipped (already exists, pass --force to overwrite):`);
+    for (const file of summary.skipped) lines.push(`    = ${file}`);
+  }
+  if (summary.missing.length) {
+    lines.push(`  missing source (${summary.missing.length}):`);
+    for (const file of summary.missing) lines.push(`    ? ${file}`);
+  }
+  if (stageResult) {
+    if (stageResult.staged) {
+      lines.push(`  staged ${stageResult.count} file(s) for commit.`);
+    } else {
+      lines.push(`  not staged: ${stageResult.reason}`);
+    }
+  }
+  if (dryRun) {
+    lines.push(`  (no files written; re-run without --dry-run to apply)`);
+  }
+  return lines.join('\n');
+}
+
+function parseCiInitArgs(rawArgs) {
+  const options = {
+    target: null,
+    dryRun: false,
+    force: false,
+    json: false,
+    noStage: false,
+    help: false,
+  };
+  const args = Array.isArray(rawArgs) ? [...rawArgs] : [];
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (arg === '--help' || arg === '-h' || arg === 'help') {
+      options.help = true;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === '--force') {
+      options.force = true;
+      continue;
+    }
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (arg === '--no-stage') {
+      options.noStage = true;
+      continue;
+    }
+    if (arg === '--target') {
+      options.target = args.shift();
+      continue;
+    }
+    if (arg.startsWith('--target=')) {
+      options.target = arg.slice('--target='.length);
+      continue;
+    }
+    const err = new Error(`Unknown ci-init argument: ${arg}`);
+    err.code = 'CI_INIT_BAD_ARG';
+    throw err;
+  }
+  return options;
+}
+
+function renderCiInitHelp() {
+  return [
+    `${TOOL_NAME} ci-init — scaffold budget-friendly GitHub Actions workflows into a target repo.`,
+    '',
+    'Usage:',
+    `  ${TOOL_NAME} ci-init [--target <path>] [--dry-run] [--force] [--no-stage] [--json]`,
+    '',
+    'Options:',
+    `  --target <path>   Repo to scaffold into (default: current working directory).`,
+    `  --dry-run         Show what would be written; do not touch the filesystem.`,
+    `  --force           Overwrite existing files instead of skipping them.`,
+    `  --no-stage        Skip the post-copy 'git add' step.`,
+    `  --json            Emit a structured summary instead of the text report.`,
+    '',
+    'Files copied (from gitguardex templates/github/workflows/):',
+    `  - ci.yml          PR-time CI with draft-skip + concurrency-cancel.`,
+    `  - ci-full.yml     Weekly cross-runtime matrix + label opt-in.`,
+    `  - cr.yml          AI code review with agent/* + draft skip.`,
+    `  - README.md       Documents the budget posture and customization knobs.`,
+    '',
+    'The command stages copied files with git add when the target is a git repo;',
+    'pair with `gx branch start "<task>" "claude-code"` to land them on a new agent',
+    'branch instead of the primary checkout.',
+  ].join('\n');
+}
+
+function runCiInitCommand(rawArgs) {
+  let options;
+  try {
+    options = parseCiInitArgs(rawArgs);
+  } catch (err) {
+    console.error(`[${TOOL_NAME}] ${err.message}`);
+    console.error(renderCiInitHelp());
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.help) {
+    console.log(renderCiInitHelp());
+    return;
+  }
+
+  const { targetRoot, operations } = planCiInitOperations(options);
+  const summary = performCiInitOperations(operations, { dryRun: options.dryRun });
+  const stageResult =
+    summary.copied.length || summary.overwritten.length
+      ? maybeStageOnAgentBranch(targetRoot, summary, options)
+      : null;
+
+  if (options.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          targetRoot,
+          dryRun: options.dryRun,
+          force: options.force,
+          summary,
+          stageResult,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    console.log(formatCiInitReport({ targetRoot, summary, stageResult, dryRun: options.dryRun }));
+  }
+
+  if (summary.missing.length > 0) {
+    process.exitCode = 1;
+  } else {
+    process.exitCode = 0;
+  }
+}
+
+module.exports = {
+  runCiInitCommand,
+  parseCiInitArgs,
+  planCiInitOperations,
+  performCiInitOperations,
+  formatCiInitReport,
+  renderCiInitHelp,
+  listWorkflowTemplates,
+};

package/src/cli/args.js

@@ -108,6 +108,14 @@ function parseCommonArgs(rawArgs, defaults) {
       options.allowProtectedBaseWrite = true;
       continue;
     }
+    if (arg === '--contract' || arg === '--full') {
+      options.contract = true;
+      continue;
+    }
+    if (arg === '--minimal' || arg === '--no-contract') {
+      options.contract = false;
+      continue;
+    }
     if (Object.prototype.hasOwnProperty.call(options, 'waitForMerge') && arg === '--wait-for-merge') {
       options.waitForMerge = true;
       continue;
@@ -177,6 +185,8 @@ function parseSetupArgs(rawArgs, defaults) {
   const setupDefaults = {
     ...defaults,
     parentWorkspaceView: false,
+    speckit: true,
+    speckitForce: false,
   };
   const forwardedArgs = [];
 
@@ -190,6 +200,19 @@ function parseSetupArgs(rawArgs, defaults) {
       setupDefaults.parentWorkspaceView = false;
       continue;
     }
+    if (arg === '--no-speckit' || arg === '--skip-speckit') {
+      setupDefaults.speckit = false;
+      continue;
+    }
+    if (arg === '--speckit') {
+      setupDefaults.speckit = true;
+      continue;
+    }
+    if (arg === '--speckit-force' || arg === '--reinstall-speckit') {
+      setupDefaults.speckit = true;
+      setupDefaults.speckitForce = true;
+      continue;
+    }
     forwardedArgs.push(arg);
   }
 
@@ -261,6 +284,69 @@ function parseReviewArgs(rawArgs) {
   };
 }
 
+function parsePrReviewArgs(rawArgs) {
+  const parsed = parseTargetFlag(rawArgs, process.cwd());
+  const options = {
+    target: parsed.target,
+    provider: 'codex',
+    pr: '',
+    post: false,
+    artifact: '',
+    timeoutMs: 10 * 60 * 1000,
+  };
+
+  for (let index = 0; index < parsed.args.length; index += 1) {
+    const arg = parsed.args[index];
+    if (arg === '--provider') {
+      const next = requireValue(parsed.args, index, '--provider');
+      if (!['codex', 'claude'].includes(next)) {
+        throw new Error(`Invalid --provider value: ${next} (expected codex|claude)`);
+      }
+      options.provider = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--pr') {
+      options.pr = requireValue(parsed.args, index, '--pr');
+      index += 1;
+      continue;
+    }
+    if (arg === '--post') {
+      options.post = true;
+      continue;
+    }
+    if (arg === '--no-post') {
+      options.post = false;
+      continue;
+    }
+    if (arg === '--artifact' || arg === '--output') {
+      options.artifact = requireValue(parsed.args, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === '--timeout-ms') {
+      const raw = requireValue(parsed.args, index, '--timeout-ms');
+      const parsedTimeout = Number.parseInt(raw, 10);
+      if (!Number.isFinite(parsedTimeout) || parsedTimeout <= 0) {
+        throw new Error('--timeout-ms requires a positive integer');
+      }
+      options.timeoutMs = parsedTimeout;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (!options.pr) {
+    throw new Error('--pr requires a pull request number');
+  }
+  if (!/^\d+$/.test(String(options.pr))) {
+    throw new Error(`--pr must be a pull request number (received: ${options.pr})`);
+  }
+
+  return options;
+}
+
 function parseAgentsArgs(rawArgs) {
   const parsed = parseTargetFlag(rawArgs, process.cwd());
   const [subcommandRaw = '', ...rest] = parsed.args;
@@ -268,14 +354,77 @@ function parseAgentsArgs(rawArgs) {
   const options = {
     target: parsed.target,
     subcommand,
+    task: '',
+    agent: '',
+    base: '',
+    claims: [],
+    count: 1,
+    agentSelectionSpecs: [],
+    panel: false,
+    terminal: process.env.GUARDEX_AGENT_TERMINAL || 'kitty',
+    dryRun: false,
     reviewIntervalSeconds: 30,
     cleanupIntervalSeconds: 60,
     idleMinutes: DEFAULT_SHADOW_CLEANUP_IDLE_MINUTES,
+    staleAgeMinutes: 24 * 60,
     pid: null,
+    branch: '',
+    json: false,
+    sessionId: '',
+    finishArgs: [],
+    metadata: {},
   };
+  let terminalProvided = false;
 
   for (let index = 0; index < rest.length; index += 1) {
     const arg = rest[index];
+    if (subcommand === 'finish') {
+      if (arg === '--json') {
+        options.json = true;
+        continue;
+      }
+      if (arg === '--session') {
+        const next = rest[index + 1];
+        if (!next) {
+          throw new Error('--session requires an agent session id');
+        }
+        options.sessionId = next;
+        index += 1;
+        continue;
+      }
+      if (arg === '--branch') {
+        const next = rest[index + 1];
+        if (!next) {
+          throw new Error('--branch requires an agent branch name');
+        }
+        options.branch = next;
+        index += 1;
+        continue;
+      }
+      options.finishArgs.push(arg);
+      if (
+        ['--base', '--commit-message', '--mode'].includes(arg) &&
+        rest[index + 1] &&
+        !rest[index + 1].startsWith('-')
+      ) {
+        options.finishArgs.push(rest[index + 1]);
+        index += 1;
+      }
+      continue;
+    }
+    if (arg === '--branch') {
+      const next = rest[index + 1];
+      if (!next) {
+        throw new Error('--branch requires an agent branch name');
+      }
+      options.branch = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
     if (arg === '--review-interval') {
       const next = rest[index + 1];
       if (!next) {
@@ -315,6 +464,19 @@ function parseAgentsArgs(rawArgs) {
       index += 1;
       continue;
     }
+    if (arg === '--older-than-minutes') {
+      const next = rest[index + 1];
+      if (!next) {
+        throw new Error('--older-than-minutes requires an integer minutes value');
+      }
+      const parsedValue = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsedValue) || parsedValue < 1) {
+        throw new Error('--older-than-minutes must be an integer >= 1');
+      }
+      options.staleAgeMinutes = parsedValue;
+      index += 1;
+      continue;
+    }
     if (arg === '--pid') {
       const next = rest[index + 1];
       if (!next) {
@@ -328,15 +490,170 @@ function parseAgentsArgs(rawArgs) {
       index += 1;
       continue;
     }
+    if (arg === '--agent') {
+      const next = rest[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('--agent requires an agent id');
+      }
+      options.agent = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--agents') {
+      const next = rest[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('--agents requires a comma-separated agent list');
+      }
+      options.agentSelectionSpecs.push(next);
+      index += 1;
+      continue;
+    }
+    if (arg === '--count') {
+      const next = rest[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('--count requires a positive integer');
+      }
+      const parsedValue = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsedValue) || parsedValue < 1) {
+        throw new Error('--count requires a positive integer');
+      }
+      options.count = parsedValue;
+      index += 1;
+      continue;
+    }
+    if (arg === '--codex-count' || arg === '--codex-accounts') {
+      const next = rest[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error(`${arg} requires a positive integer`);
+      }
+      const parsedValue = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsedValue) || parsedValue < 1) {
+        throw new Error(`${arg} requires a positive integer`);
+      }
+      options.agent = 'codex';
+      options.count = parsedValue;
+      index += 1;
+      continue;
+    }
+    if (arg === '--panel') {
+      options.panel = true;
+      continue;
+    }
+    if (arg === '--terminal') {
+      const next = rest[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('--terminal requires kitty or none');
+      }
+      options.terminal = next;
+      terminalProvided = true;
+      index += 1;
+      continue;
+    }
+    if (arg === '--base') {
+      const next = rest[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('--base requires a branch name');
+      }
+      options.base = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === '--claim') {
+      const next = rest[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('--claim requires a file path');
+      }
+      options.claims.push(next);
+      index += 1;
+      continue;
+    }
+    if (arg === '--meta') {
+      const next = rest[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('--meta requires a key=value pair');
+      }
+      const splitIndex = next.indexOf('=');
+      const key = splitIndex >= 0 ? next.slice(0, splitIndex).trim() : '';
+      if (!key) {
+        throw new Error('--meta requires a non-empty key=value pair');
+      }
+      options.metadata[key] = splitIndex >= 0 ? next.slice(splitIndex + 1) : '';
+      index += 1;
+      continue;
+    }
+    if (!arg.startsWith('-') && options.subcommand === 'start' && !options.task) {
+      options.task = arg;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
 
-  if (!['start', 'stop', 'status'].includes(options.subcommand)) {
+  if (!['start', 'stop', 'status', 'files', 'diff', 'locks', 'finish', 'cleanup-sessions'].includes(options.subcommand)) {
     throw new Error(`Unknown agents subcommand: ${options.subcommand}`);
   }
   if (options.pid !== null && options.subcommand !== 'stop') {
     throw new Error('--pid is only supported with `gx agents stop`');
   }
+  if (
+    (options.task || options.agent || options.base || options.claims.length > 0 || Object.keys(options.metadata).length > 0 || terminalProvided) &&
+    options.subcommand !== 'start'
+  ) {
+    throw new Error('--task, --agent, --agents, --count, --base, --claim, --meta, --terminal, and --panel are only supported with `gx agents start`');
+  }
+  if (
+    (options.agentSelectionSpecs.length > 0 || options.count !== 1 || options.panel) &&
+    options.subcommand !== 'start'
+  ) {
+    throw new Error('--agents, --count, and --panel are only supported with `gx agents start`');
+  }
+  if (options.dryRun && !['start', 'cleanup-sessions'].includes(options.subcommand)) {
+    throw new Error('--dry-run is only supported with `gx agents start|cleanup-sessions`');
+  }
+  if (options.subcommand === 'start' && options.dryRun && !options.task && !(options.panel && !options.json)) {
+    throw new Error('gx agents start --dry-run requires a task');
+  }
+  if (
+    options.subcommand === 'start' &&
+    !options.task &&
+    !options.panel &&
+    (options.agentSelectionSpecs.length > 0 || options.count !== 1)
+  ) {
+    throw new Error('gx agents start --agents|--count requires a task');
+  }
+  if (options.claims.length > 0 && !options.task && !options.panel) {
+    throw new Error('gx agents start --claim requires a task');
+  }
+  if (['files', 'diff', 'locks'].includes(options.subcommand) && !options.branch) {
+    throw new Error('--branch requires an agent branch name');
+  }
+  if (options.subcommand === 'finish') {
+    if (!options.sessionId && !options.branch) {
+      throw new Error('agents finish requires --session <id> or --branch <agent/...>');
+    }
+    if (options.sessionId && options.branch) {
+      throw new Error('agents finish accepts only one of --session or --branch');
+    }
+  }
+  if (options.branch && !['files', 'diff', 'locks', 'finish'].includes(options.subcommand)) {
+    throw new Error('--branch is only supported with `gx agents files|diff|locks|finish`');
+  }
+  if (
+    options.json &&
+    !['status', 'files', 'diff', 'locks', 'cleanup-sessions', 'finish'].includes(options.subcommand) &&
+    !(options.subcommand === 'start' && options.dryRun)
+  ) {
+    throw new Error('--json is only supported with `gx agents start --dry-run|status|files|diff|locks|finish|cleanup-sessions`');
+  }
+  if (options.subcommand === 'start' && options.json && !options.dryRun) {
+    throw new Error('gx agents start --json requires --dry-run');
+  }
+  if (options.staleAgeMinutes !== 24 * 60 && options.subcommand !== 'cleanup-sessions') {
+    throw new Error('--older-than-minutes is only supported with `gx agents cleanup-sessions`');
+  }
 
   return options;
 }
@@ -771,9 +1088,14 @@ function parseFinishArgs(rawArgs, defaults = {}) {
     keepRemote: false,
     noAutoCommit: false,
     parentGitlinkCommit: defaults.parentGitlinkCommit ?? true,
+    advanceSubmodules: false,
     failFast: false,
     commitMessage: '',
     mergeMode: defaults.mergeMode || 'pr',
+    skipPreflight: false,
+    gateReview: defaults.gateReview ?? false,
+    reviewProvider: defaults.reviewProvider || 'codex',
+    allowNoChecks: false,
   };
 
   for (let index = 0; index < rawArgs.length; index += 1) {
@@ -878,6 +1200,39 @@ function parseFinishArgs(rawArgs, defaults = {}) {
       options.failFast = true;
       continue;
     }
+    if (arg === '--advance-submodules') {
+      options.advanceSubmodules = true;
+      continue;
+    }
+    if (arg === '--no-advance-submodules') {
+      options.advanceSubmodules = false;
+      continue;
+    }
+    if (arg === '--skip-preflight') {
+      options.skipPreflight = true;
+      continue;
+    }
+    if (arg === '--gate-review') {
+      options.gateReview = true;
+      continue;
+    }
+    if (arg === '--no-gate-review' || arg === '--skip-review-gate') {
+      options.gateReview = false;
+      continue;
+    }
+    if (arg === '--allow-no-checks') {
+      options.allowNoChecks = true;
+      continue;
+    }
+    if (arg === '--review-provider') {
+      const next = rawArgs[index + 1];
+      if (!next || !['codex', 'claude'].includes(next)) {
+        throw new Error('--review-provider requires a value of codex|claude');
+      }
+      options.reviewProvider = next;
+      index += 1;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
 
@@ -891,13 +1246,12 @@ function parseFinishArgs(rawArgs, defaults = {}) {
 module.exports = {
   requireValue,
   normalizeManagedForcePath,
-  collectForceManagedPaths,
   parseCommonArgs,
-  parseRepoTraversalArgs,
   parseSetupArgs,
   parseDoctorArgs,
   parseTargetFlag,
   parseReviewArgs,
+  parsePrReviewArgs,
   parseAgentsArgs,
   parseReportArgs,
   parseSyncArgs,