@imdeadpool/guardex 7.0.41 → 7.0.43

package/src/kitty/command.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const cp = require('node:child_process');
+
+const DEFAULT_KITTY_BIN = 'kitty';
+
+function text(value, fallback = '') {
+  if (typeof value === 'string') return value.trim() || fallback;
+  if (value === null || value === undefined) return fallback;
+  return String(value).trim() || fallback;
+}
+
+function resolveKittyBin(options = {}) {
+  return text(options.kittyBin || options.bin || process.env.GUARDEX_KITTY_BIN, DEFAULT_KITTY_BIN);
+}
+
+function assertArgs(args) {
+  if (!Array.isArray(args)) {
+    throw new TypeError('kitty args must be an array');
+  }
+  for (const arg of args) {
+    if (typeof arg !== 'string') {
+      throw new TypeError('kitty args must contain only strings');
+    }
+  }
+}
+
+function commandShape(cmd, args, options = {}) {
+  const command = {
+    cmd,
+    args: [...args],
+  };
+  if (Object.prototype.hasOwnProperty.call(options, 'input')) {
+    command.input = options.input === undefined || options.input === null ? '' : String(options.input);
+  }
+  return command;
+}
+
+function runnerOptions(options = {}) {
+  return {
+    cwd: options.cwd,
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+    encoding: 'utf8',
+    input: options.input,
+    stdio: options.stdio || 'pipe',
+    timeout: options.timeout,
+  };
+}
+
+function defaultRunner(cmd, args, options = {}) {
+  return cp.spawnSync(cmd, args, runnerOptions(options));
+}
+
+function runnerFor(options = {}) {
+  if (typeof options.runner === 'function') return options.runner;
+  if (options.runtime && typeof options.runtime.run === 'function') return options.runtime.run;
+  return defaultRunner;
+}
+
+function dryRunOptions(options = {}) {
+  const result = {};
+  for (const key of ['cwd', 'env', 'input', 'stdio', 'timeout']) {
+    if (Object.prototype.hasOwnProperty.call(options, key) && options[key] !== undefined) {
+      result[key] = options[key];
+    }
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function runKitty(args, options = {}) {
+  assertArgs(args);
+  const cmd = resolveKittyBin(options);
+  const command = commandShape(cmd, args, options);
+
+  if (options.dryRun) {
+    const result = {
+      dryRun: true,
+      commands: [command],
+    };
+    const optionsForReport = dryRunOptions(options);
+    if (optionsForReport) result.options = optionsForReport;
+    return result;
+  }
+
+  return runnerFor(options)(cmd, [...args], runnerOptions(options));
+}
+
+function isKittyAvailable(options = {}) {
+  const result = runKitty(['@', 'ls'], {
+    ...options,
+    stdio: 'pipe',
+  });
+  if (result && result.dryRun) return result;
+  return Boolean(result && result.status === 0 && !result.error);
+}
+
+module.exports = {
+  isKittyAvailable,
+  runKitty,
+  resolveKittyBin,
+};

package/src/kitty/runtime.js

@@ -0,0 +1,250 @@
+'use strict';
+
+const {
+  isKittyAvailable,
+  resolveKittyBin,
+  runKitty,
+} = require('./command');
+
+function text(value, fallback = '') {
+  if (typeof value === 'string') return value.trim() || fallback;
+  if (value === null || value === undefined) return fallback;
+  return String(value).trim() || fallback;
+}
+
+function requireText(value, name) {
+  const normalized = text(value);
+  if (!normalized) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return normalized;
+}
+
+function appendOption(args, flag, value) {
+  const normalized = text(value);
+  if (normalized) args.push(flag, normalized);
+  return args;
+}
+
+function normalizeEnvEntries(env = {}) {
+  if (!env) return [];
+  if (Array.isArray(env)) {
+    return env.map((entry) => {
+      if (Array.isArray(entry)) {
+        const key = requireText(entry[0], 'kitty env key');
+        const value = entry.length > 1 && entry[1] !== undefined && entry[1] !== null ? String(entry[1]) : '';
+        return `${key}=${value}`;
+      }
+      return requireText(entry, 'kitty env');
+    });
+  }
+  if (typeof env !== 'object') {
+    throw new TypeError('kitty env must be an object, array, or undefined');
+  }
+  return Object.keys(env)
+    .sort()
+    .map((key) => `${requireText(key, 'kitty env key')}=${env[key] === undefined || env[key] === null ? '' : String(env[key])}`);
+}
+
+function appendEnv(args, env) {
+  for (const entry of normalizeEnvEntries(env)) {
+    args.push('--env', entry);
+  }
+  return args;
+}
+
+function normalizeCommandArgv(options = {}) {
+  if (options.argv === undefined && options.commandArgv === undefined && Object.prototype.hasOwnProperty.call(options, 'command') && !Array.isArray(options.command)) {
+    throw new TypeError('kitty command argv must be an array');
+  }
+  const commandArgv = options.argv || options.commandArgv || (Array.isArray(options.command) ? options.command : undefined);
+  if (commandArgv === undefined || commandArgv === null) return [];
+  if (!Array.isArray(commandArgv)) {
+    throw new TypeError('kitty command argv must be an array');
+  }
+  return commandArgv.map((arg) => {
+    if (arg === undefined || arg === null) {
+      throw new TypeError('kitty command argv values must be strings');
+    }
+    return String(arg);
+  });
+}
+
+function appendCommandArgv(args, options = {}) {
+  const commandArgv = normalizeCommandArgv(options);
+  if (commandArgv.length > 0) args.push('--', ...commandArgv);
+  return args;
+}
+
+function commandShape(args, options = {}) {
+  const command = {
+    cmd: resolveKittyBin(options),
+    args,
+  };
+  if (Object.prototype.hasOwnProperty.call(options, 'input')) {
+    command.input = options.input === undefined || options.input === null ? '' : String(options.input);
+  }
+  return command;
+}
+
+function buildKittyLaunchCommand(options = {}) {
+  const args = ['@', 'launch'];
+  appendOption(args, '--type', text(options.type, 'window'));
+  appendOption(args, '--location', options.location);
+  appendOption(args, '--cwd', options.cwd);
+  appendOption(args, '--title', options.title);
+  appendEnv(args, options.env);
+  appendCommandArgv(args, options);
+  return commandShape(args, options);
+}
+
+function runCommand(command, action, options = {}) {
+  const runOptions = {
+    ...options,
+    kittyBin: command.cmd,
+    action,
+  };
+  if (Object.prototype.hasOwnProperty.call(command, 'input')) {
+    runOptions.input = command.input;
+  } else if (Object.prototype.hasOwnProperty.call(options, 'input')) {
+    runOptions.input = options.input;
+  }
+  return runKitty(command.args, runOptions);
+}
+
+function cloneCommand(command) {
+  if (!command || typeof command !== 'object' || !Array.isArray(command.args)) {
+    throw new TypeError('kitty cockpit command must include args');
+  }
+  const clone = {
+    cmd: requireText(command.cmd, 'kitty cockpit command cmd'),
+    args: command.args.map((arg) => {
+      if (arg === undefined || arg === null) {
+        throw new TypeError('kitty cockpit command args must be strings');
+      }
+      return String(arg);
+    }),
+  };
+  if (Object.prototype.hasOwnProperty.call(command, 'input')) {
+    clone.input = command.input === undefined || command.input === null ? '' : String(command.input);
+  }
+  return clone;
+}
+
+function cockpitCommands(plan = {}) {
+  if (!plan || typeof plan !== 'object') {
+    throw new TypeError('kitty cockpit plan must be an object');
+  }
+  const commands = Array.isArray(plan.commands)
+    ? plan.commands
+    : Array.isArray(plan.steps)
+      ? plan.steps.map((step) => step && step.command).filter(Boolean)
+      : [];
+  return commands.map(cloneCommand);
+}
+
+function assertCommandResult(command, result) {
+  if (result && result.error) throw result.error;
+  if (!result || result.status === 0) return result;
+  const detail = String(result.stderr || result.stdout || '').trim();
+  throw new Error(`kitty cockpit command failed: ${command.cmd} ${command.args.join(' ')}${detail ? `: ${detail}` : ''}`);
+}
+
+function openKittyCockpit(options = {}) {
+  const plan = options.plan && typeof options.plan === 'object' ? options.plan : options;
+  const commands = cockpitCommands(plan);
+  const dryRun = Boolean(options.dryRun || plan.dryRun);
+
+  if (dryRun) {
+    return {
+      dryRun: true,
+      action: 'open-kitty-cockpit',
+      commands,
+      plan,
+    };
+  }
+
+  const results = commands.map((command) => (
+    assertCommandResult(command, runCommand(command, 'open-kitty-cockpit', options))
+  ));
+  return {
+    action: 'open-kitty-cockpit',
+    commands,
+    results,
+  };
+}
+
+function launchKittyWindow(options = {}) {
+  return runCommand(
+    buildKittyLaunchCommand({
+      ...options,
+      type: text(options.type, 'window'),
+    }),
+    'launch-window',
+    options,
+  );
+}
+
+function launchKittyTab(options = {}) {
+  return runCommand(
+    buildKittyLaunchCommand({
+      ...options,
+      type: 'tab',
+    }),
+    'launch-tab',
+    options,
+  );
+}
+
+function launchKittyPane(options = {}) {
+  return runCommand(
+    buildKittyLaunchCommand({
+      ...options,
+      type: 'window',
+      location: text(options.location, 'vsplit'),
+    }),
+    'launch-pane',
+    options,
+  );
+}
+
+function targetMatch(target) {
+  if (target && typeof target === 'object') {
+    const explicit = text(target.match || target.kittyMatch);
+    if (explicit) return explicit;
+
+    const id = text(target.id || target.windowId || target.kittyWindowId || target.paneId || target.target);
+    if (id) return `id:${id}`;
+
+    const title = text(target.title || target.windowTitle || target.kittyTitle);
+    if (title) return `title:${title}`;
+  } else {
+    const id = text(target);
+    if (id) return `id:${id}`;
+  }
+  throw new TypeError('kitty target must include id, title, or match');
+}
+
+function sendTextToKitty(target, value, options = {}) {
+  return runKitty(['@', 'send-text', '--match', targetMatch(target), '--stdin'], {
+    ...options,
+    input: value === undefined || value === null ? '' : String(value),
+    stdio: options.stdio || 'pipe',
+  });
+}
+
+function setKittyWindowTitle(target, title, options = {}) {
+  return runKitty(['@', 'set-window-title', '--match', targetMatch(target), requireText(title, 'kitty window title')], options);
+}
+
+module.exports = {
+  isKittyAvailable,
+  runKitty,
+  buildKittyLaunchCommand,
+  launchKittyWindow,
+  launchKittyTab,
+  launchKittyPane,
+  openKittyCockpit,
+  sendTextToKitty,
+  setKittyWindowTitle,
+};

package/src/output/index.js

@@ -347,7 +347,7 @@ REPO TOGGLE
 ${repoToggleLines().join('\n')}
 
 NOTES
-  - No command = ${invoked} status (compact in a TTY; pass --verbose for full services + help tree).
+  - No command = ${invoked} status (compact by default; pass --verbose for full services + help tree).
   - ${invoked} init is an alias of ${invoked} setup.
   - Global installs need Y/N approval; GitHub CLI (gh) is required for PR automation.
   - Target another repo: ${invoked} <cmd> --target <repo-path>.

package/src/pr-review.js

@@ -0,0 +1,241 @@
+const {
+  fs,
+  path,
+  os,
+  GH_BIN,
+} = require('./context');
+const { run } = require('./core/runtime');
+
+const TOOL_PREFIX = '[gitguardex]';
+const VALID_SEVERITIES = new Set(['low', 'medium', 'high', 'critical']);
+
+function normalizeProvider(raw) {
+  const provider = String(raw || 'codex').trim().toLowerCase();
+  if (!['codex', 'claude'].includes(provider)) {
+    throw new Error(`Invalid provider: ${raw}`);
+  }
+  return provider;
+}
+
+function commandForProvider(provider, prompt) {
+  if (provider === 'claude') {
+    return { cmd: 'claude', args: ['-p', prompt] };
+  }
+  return { cmd: 'codex', args: ['exec', prompt] };
+}
+
+function compactReviewPrompt(diff) {
+  return [
+    'You are gitguardex-code-assist, a PR review runner.',
+    'Review this GitHub PR diff for correctness bugs, regressions, security issues, and missing tests.',
+    'Return JSON only. Shape:',
+    '{"findings":[{"path":"file","line":123,"severity":"low|medium|high|critical","message":"concise finding","suggestion":"optional replacement or fix"}]}',
+    'Rules: path and line must point to changed lines in the diff. Use an empty findings array when nothing is worth commenting.',
+    '',
+    'PR diff:',
+    diff,
+  ].join('\n');
+}
+
+function extractJsonPayload(text) {
+  const raw = String(text || '').trim();
+  if (!raw) return { findings: [] };
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = fenced ? fenced[1].trim() : raw;
+  try {
+    return JSON.parse(candidate);
+  } catch (_error) {
+    const objectStart = candidate.indexOf('{');
+    const objectEnd = candidate.lastIndexOf('}');
+    if (objectStart >= 0 && objectEnd > objectStart) {
+      return JSON.parse(candidate.slice(objectStart, objectEnd + 1));
+    }
+    const arrayStart = candidate.indexOf('[');
+    const arrayEnd = candidate.lastIndexOf(']');
+    if (arrayStart >= 0 && arrayEnd > arrayStart) {
+      return { findings: JSON.parse(candidate.slice(arrayStart, arrayEnd + 1)) };
+    }
+    throw new Error('Review provider did not return parseable JSON findings');
+  }
+}
+
+function normalizeFinding(rawFinding) {
+  const pathValue = String(rawFinding?.path || '').trim();
+  const line = Number.parseInt(String(rawFinding?.line || ''), 10);
+  const severity = String(rawFinding?.severity || 'medium').trim().toLowerCase();
+  const message = String(rawFinding?.message || '').trim();
+  const suggestion = String(rawFinding?.suggestion || '').trim();
+  if (!pathValue || !Number.isInteger(line) || line <= 0 || !message) {
+    return null;
+  }
+  return {
+    path: pathValue,
+    line,
+    severity: VALID_SEVERITIES.has(severity) ? severity : 'medium',
+    message,
+    suggestion,
+  };
+}
+
+function normalizeFindings(providerOutput) {
+  const payload = extractJsonPayload(providerOutput);
+  const rawFindings = Array.isArray(payload) ? payload : payload.findings;
+  if (!Array.isArray(rawFindings)) {
+    throw new Error('Review provider JSON must contain a findings array');
+  }
+  return rawFindings.map(normalizeFinding).filter(Boolean);
+}
+
+function findingBody(finding) {
+  const lines = [`**${finding.severity.toUpperCase()}** ${finding.message}`];
+  if (finding.suggestion) {
+    lines.push('', 'Suggested fix:', '```suggestion', finding.suggestion, '```');
+  }
+  return lines.join('\n');
+}
+
+function renderMarkdownReview({ pr, provider, findings }) {
+  const lines = [
+    `# GitGuardex PR Review`,
+    '',
+    `- PR: #${pr}`,
+    `- Provider: ${provider}`,
+    `- Findings: ${findings.length}`,
+    '',
+  ];
+  if (findings.length === 0) {
+    lines.push('No findings.');
+  } else {
+    for (const finding of findings) {
+      lines.push(`## ${finding.severity.toUpperCase()} ${finding.path}:${finding.line}`);
+      lines.push('');
+      lines.push(finding.message);
+      if (finding.suggestion) {
+        lines.push('', '```suggestion', finding.suggestion, '```');
+      }
+      lines.push('');
+    }
+  }
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n')}\n`;
+}
+
+function defaultArtifactPath(repoRoot, pr) {
+  return path.join(repoRoot, '.gitguardex', 'pr-reviews', `pr-${pr}.md`);
+}
+
+function writeArtifact(repoRoot, artifactPath, payload) {
+  const outputPath = artifactPath
+    ? path.resolve(repoRoot, artifactPath)
+    : defaultArtifactPath(repoRoot, payload.pr);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, renderMarkdownReview(payload), 'utf8');
+  return outputPath;
+}
+
+function githubAuthAvailable(env = process.env, runner = run) {
+  if (env.GITHUB_TOKEN || env.GH_TOKEN) return true;
+  const result = runner(GH_BIN, ['auth', 'status'], { timeout: 15_000 });
+  return result.status === 0;
+}
+
+function fetchPrDiff(pr, repoRoot, runner = run) {
+  const result = runner(GH_BIN, ['pr', 'diff', String(pr)], { cwd: repoRoot, timeout: 120_000 });
+  if (result.status !== 0) {
+    throw new Error(`gh pr diff ${pr} failed${result.stderr ? `\n${result.stderr.trim()}` : ''}`);
+  }
+  return result.stdout || '';
+}
+
+function runProviderReview(provider, diff, repoRoot, timeoutMs, runner = run) {
+  const prompt = compactReviewPrompt(diff);
+  const command = commandForProvider(provider, prompt);
+  const result = runner(command.cmd, command.args, { cwd: repoRoot, timeout: timeoutMs });
+  if (result.status !== 0) {
+    throw new Error(`${provider} review failed${result.stderr ? `\n${result.stderr.trim()}` : ''}`);
+  }
+  return normalizeFindings(result.stdout || '');
+}
+
+function postGithubReview(pr, findings, repoRoot, runner = run) {
+  const comments = findings.map((finding) => ({
+    path: finding.path,
+    line: finding.line,
+    side: 'RIGHT',
+    body: findingBody(finding),
+  }));
+  const body = findings.length > 0
+    ? `GitGuardex code-assist found ${findings.length} issue(s).`
+    : 'GitGuardex code-assist found no issues worth inline comments.';
+  const payload = {
+    event: 'COMMENT',
+    body,
+    comments,
+  };
+  const inputPath = path.join(os.tmpdir(), `gitguardex-pr-review-${process.pid}-${Date.now()}.json`);
+  fs.writeFileSync(inputPath, JSON.stringify(payload), 'utf8');
+  try {
+    const result = runner(GH_BIN, [
+      'api',
+      `repos/:owner/:repo/pulls/${pr}/reviews`,
+      '--method',
+      'POST',
+      '--input',
+      inputPath,
+    ], { cwd: repoRoot, timeout: 120_000 });
+    if (result.status !== 0) {
+      throw new Error(`gh api review post failed${result.stderr ? `\n${result.stderr.trim()}` : ''}`);
+    }
+    return result;
+  } finally {
+    try {
+      fs.unlinkSync(inputPath);
+    } catch (_error) {
+      // best effort cleanup for temp API payload
+    }
+  }
+}
+
+function runPrReview(options, deps = {}) {
+  const runner = deps.run || run;
+  const repoRoot = path.resolve(options.target || process.cwd());
+  const provider = normalizeProvider(options.provider);
+  const pr = String(options.pr);
+  const diff = fetchPrDiff(pr, repoRoot, runner);
+  const findings = runProviderReview(provider, diff, repoRoot, options.timeoutMs, runner);
+  const payload = { pr, provider, findings };
+
+  if (!options.post) {
+    const artifactPath = writeArtifact(repoRoot, options.artifact, payload);
+    return { posted: false, artifactPath, findings };
+  }
+
+  if (!githubAuthAvailable(process.env, runner)) {
+    const artifactPath = writeArtifact(repoRoot, options.artifact, payload);
+    return { posted: false, artifactPath, findings, reason: 'github-auth-unavailable' };
+  }
+
+  postGithubReview(pr, findings, repoRoot, runner);
+  return { posted: true, artifactPath: '', findings };
+}
+
+function printPrReviewResult(result) {
+  if (result.posted) {
+    console.log(`${TOOL_PREFIX} Posted PR review with ${result.findings.length} finding(s).`);
+    return;
+  }
+  if (result.reason === 'github-auth-unavailable') {
+    console.log(`${TOOL_PREFIX} GitHub auth unavailable; wrote PR review artifact: ${result.artifactPath}`);
+    return;
+  }
+  console.log(`${TOOL_PREFIX} Wrote PR review artifact: ${result.artifactPath}`);
+}
+
+module.exports = {
+  compactReviewPrompt,
+  commandForProvider,
+  extractJsonPayload,
+  normalizeFindings,
+  renderMarkdownReview,
+  runPrReview,
+  printPrReviewResult,
+};

package/src/scaffold/index.js

@@ -539,6 +539,24 @@ function ensureAgentsSnippet(repoRoot, dryRun) {
   return { status: 'updated', file: 'AGENTS.md' };
 }
 
+function ensureClaudeAgentsLink(repoRoot, dryRun) {
+  const claudePath = path.join(repoRoot, 'CLAUDE.md');
+  try {
+    fs.lstatSync(claudePath);
+    return { status: 'unchanged', file: 'CLAUDE.md', note: 'existing path preserved' };
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  if (!dryRun) {
+    fs.symlinkSync('AGENTS.md', claudePath);
+  }
+
+  return { status: dryRun ? 'would-create' : 'created', file: 'CLAUDE.md', note: 'symlink to AGENTS.md' };
+}
+
 function ensureManagedGitignore(repoRoot, dryRun) {
   const gitignorePath = path.join(repoRoot, '.gitignore');
   const managedBlock = [
@@ -763,6 +781,7 @@ module.exports = {
   installUserLevelAsset,
   removeLegacyManagedRepoFile,
   ensureAgentsSnippet,
+  ensureClaudeAgentsLink,
   ensureManagedGitignore,
   parseJsonObjectLikeFile,
   buildRepoVscodeSettings,