agent-gate-installer 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# agent-gate-installer
+
+One-command setup for the [agent-gate](https://github.com/jl-cmd/agent-gate) prompt evaluation gate for Claude Code.
+
+## Prerequisites
+
+- Node.js 18+
+- Python 3.12+
+- git
+- A GitHub personal access token with access to `jl-cmd/agent-gate`
+
+## Install
+
+```bash
+GH_TOKEN=github_pat_XXXXX npx agent-gate-installer
+```
+
+Or set `GH_TOKEN` in your environment first:
+
+```bash
+export GH_TOKEN=github_pat_XXXXX
+npx agent-gate-installer
+```
+
+Without `GH_TOKEN`, the installer prompts interactively.
+
+### What it does
+
+1. Detects Python 3.12+ (tries `python3`, `python`, `py -3`)
+2. Clones `jl-cmd/agent-gate` to `~/.claude/agent-gate/`
+3. Creates a Python venv at `~/.claude/agent-gate/.venv/`
+4. Installs all agent-gate sub-packages in editable mode
+5. Merges 3 hooks into `~/.claude/settings.json` (idempotent)
+6. Registers the MCP server in `~/.claude/settings.json`
+7. Verifies the installation
+
+Restart Claude Code after installing.
+
+## Update
+
+```bash
+npx agent-gate-installer --update
+```
+
+Pulls the latest code and reinstalls packages.
+
+## Uninstall
+
+```bash
+npx agent-gate-installer --uninstall
+```
+
+Removes `~/.claude/agent-gate/`, the hooks, and the MCP server entry from settings.json.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--verbose` | Show detailed output from each step |
+| `--non-interactive` | Fail if GH_TOKEN is missing (for CI/automation) |
+| `--update` | Pull latest and reinstall packages |
+| `--uninstall` | Remove agent-gate completely |
+| `--help` | Show usage information |
+
+## Cloud setup script
+
+For Claude Code on the web environments:
+
+```bash
+GH_TOKEN="${GH_TOKEN}" npx agent-gate-installer --non-interactive --verbose
+```
+
+Set `GH_TOKEN` as an environment variable in your cloud environment settings.
+
+## Cross-platform
+
+Works on Linux, macOS, and Windows. Python detection and venv paths adapt automatically.

package/bin/install.mjs

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { join } from "node:path";
+import { homedir, platform } from "node:os";
+
+const CLAUDE_HOME = join(homedir(), ".claude");
+const INSTALL_DIR = join(CLAUDE_HOME, "agent-gate");
+const SETTINGS_PATH = join(CLAUDE_HOME, "settings.json");
+const REPO_URL = "https://github.com/jl-cmd/agent-gate.git";
+const MINIMUM_PYTHON_VERSION = [3, 12];
+const IS_WINDOWS = platform() === "win32";
+
+const HOOK_FILENAMES = ["gate_enforcer.py", "gate_trigger.py", "session_cleanup.py"];
+const HOOK_EVENTS = [
+  { event: "PreToolUse", matcher: "Read|Write|Edit|Bash|Glob|Grep|Agent|Task", filename: "gate_enforcer.py" },
+  { event: "UserPromptSubmit", matcher: "", filename: "gate_trigger.py" },
+  { event: "SessionStart", matcher: null, filename: "session_cleanup.py" },
+];
+
+const flags = new Set(process.argv.slice(2));
+const verbose = flags.has("--verbose");
+const nonInteractive = flags.has("--non-interactive");
+
+function log(message) {
+  console.log(message);
+}
+
+function logVerbose(message) {
+  if (verbose) console.log(message);
+}
+
+function run(command, options = {}) {
+  const stdio = verbose ? "inherit" : "pipe";
+  return execSync(command, { encoding: "utf8", stdio, ...options });
+}
+
+function detectPython() {
+  const candidates = IS_WINDOWS
+    ? ["python", "python3", "py -3"]
+    : ["python3", "python", "py -3"];
+
+  for (const candidate of candidates) {
+    try {
+      const output = execSync(`${candidate} --version`, { encoding: "utf8", stdio: "pipe" });
+      if (!output.includes("Python 3")) continue;
+      const match = output.match(/Python (\d+)\.(\d+)/);
+      if (!match) continue;
+      const major = parseInt(match[1], 10);
+      const minor = parseInt(match[2], 10);
+      if (major < MINIMUM_PYTHON_VERSION[0]) continue;
+      if (major === MINIMUM_PYTHON_VERSION[0] && minor < MINIMUM_PYTHON_VERSION[1]) continue;
+      return { command: candidate.split(" ")[0], args: candidate.includes(" ") ? candidate.split(" ").slice(1) : [], version: `${major}.${minor}`, full: candidate };
+    } catch {
+      continue;
+    }
+  }
+  log("Error: Python 3.12+ is required but not found.");
+  log("Install from https://www.python.org/downloads/");
+  process.exit(1);
+}
+
+function getVenvPython(venvDirectory) {
+  return IS_WINDOWS
+    ? join(venvDirectory, "Scripts", "python.exe")
+    : join(venvDirectory, "bin", "python");
+}
+
+function readSettings() {
+  if (!existsSync(SETTINGS_PATH)) return {};
+  const raw = readFileSync(SETTINGS_PATH, "utf8");
+  try {
+    return JSON.parse(raw);
+  } catch {
+    log(`Error: ${SETTINGS_PATH} contains malformed JSON. Fix it manually before running the installer.`);
+    process.exit(1);
+  }
+}
+
+function writeSettings(settings) {
+  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 4) + "\n", "utf8");
+}
+
+function hookCommandContains(hookEntry, filename) {
+  return hookEntry.hooks?.some((each_hook) => each_hook.command?.includes(filename));
+}
+
+function mergeHooks(settings, venvPython) {
+  settings.hooks = settings.hooks || {};
+  let updatedCount = 0;
+  let addedCount = 0;
+
+  for (const { event, matcher, filename } of HOOK_EVENTS) {
+    const hookCommand = `"${venvPython}" "${join(INSTALL_DIR, "hooks", filename)}"`;
+    const newEntry = { type: "command", command: hookCommand, timeout: 10000 };
+    const newGroup = matcher !== null
+      ? { matcher, hooks: [newEntry] }
+      : { hooks: [newEntry] };
+
+    settings.hooks[event] = settings.hooks[event] || [];
+    const existingIndex = settings.hooks[event].findIndex((group) => hookCommandContains(group, filename));
+
+    if (existingIndex >= 0) {
+      const existingGroup = settings.hooks[event][existingIndex];
+      const hookIndex = existingGroup.hooks.findIndex((each_hook) => each_hook.command?.includes(filename));
+      if (hookIndex >= 0) {
+        existingGroup.hooks[hookIndex] = newEntry;
+      }
+      updatedCount++;
+    } else {
+      settings.hooks[event].push(newGroup);
+      addedCount++;
+    }
+  }
+
+  if (updatedCount > 0 && addedCount === 0) {
+    log("  ~ Updated 3 existing hooks in settings.json");
+  } else {
+    log(`  + Merged ${addedCount + updatedCount} hooks into settings.json`);
+  }
+}
+
+function registerMcpServer(settings, venvPython) {
+  settings.mcpServers = settings.mcpServers || {};
+  settings.mcpServers["agent-gate"] = {
+    type: "stdio",
+    command: venvPython,
+    args: [join(INSTALL_DIR, "src", "agent_gate", "server.py")],
+  };
+  log("  + Registered agent-gate MCP server");
+}
+
+async function promptForToken() {
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    readline.question("Enter your GitHub token (GH_TOKEN): ", (answer) => {
+      readline.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function install() {
+  log("Installing agent-gate...\n");
+
+  let token = process.env.GH_TOKEN || "";
+  if (!token) {
+    if (nonInteractive) {
+      log("Error: GH_TOKEN environment variable is required in --non-interactive mode.");
+      log("Create a fine-grained PAT at: https://github.com/settings/personal-access-tokens/new");
+      process.exit(1);
+    }
+    token = await promptForToken();
+    if (!token) {
+      log("Error: No token provided.");
+      process.exit(1);
+    }
+  }
+
+  const python = detectPython();
+  logVerbose(`  Detected Python: ${python.full} (${python.version})`);
+
+  mkdirSync(CLAUDE_HOME, { recursive: true });
+
+  if (existsSync(join(INSTALL_DIR, ".git"))) {
+    log("  ~ agent-gate already cloned, pulling latest...");
+    try {
+      run(`git -C "${INSTALL_DIR}" pull`);
+    } catch {
+      log("  ! git pull failed (continuing with existing checkout)");
+    }
+  } else {
+    log("  + Cloning agent-gate...");
+    const authenticatedUrl = `https://${token}@github.com/jl-cmd/agent-gate.git`;
+    try {
+      run(`git clone "${authenticatedUrl}" "${INSTALL_DIR}"`);
+      log("  + Cloned agent-gate to ~/.claude/agent-gate/");
+    } catch {
+      log("Error: git clone failed. Is GH_TOKEN set correctly?");
+      log("Create a fine-grained PAT at: https://github.com/settings/personal-access-tokens/new");
+      process.exit(1);
+    }
+  }
+
+  const venvDirectory = join(INSTALL_DIR, ".venv");
+  const venvPython = getVenvPython(venvDirectory);
+
+  if (existsSync(venvDirectory)) {
+    log("  ~ venv already exists");
+  } else {
+    log("  + Creating Python venv...");
+    try {
+      run(`${python.full} -m venv "${venvDirectory}"`);
+      log("  + Created Python venv");
+    } catch (error) {
+      log(`Error: Failed to create venv. ${error.message}`);
+      process.exit(1);
+    }
+  }
+
+  log("  + Installing agent-gate packages...");
+  const packagePaths = [
+    join(INSTALL_DIR, "packages", "agent-gate-core"),
+    join(INSTALL_DIR, "packages", "agent-gate-claude"),
+    join(INSTALL_DIR, "packages", "agent-gate-prompt-refinement"),
+    INSTALL_DIR,
+  ];
+  const editableArgs = packagePaths.map((each_path) => `-e "${each_path}"`).join(" ");
+  try {
+    run(`"${venvPython}" -m pip install ${editableArgs}`);
+    log("  + Installed agent-gate packages");
+  } catch {
+    log("Error: pip install failed. Check Python version and network connectivity.");
+    process.exit(1);
+  }
+
+  const settings = readSettings();
+  mergeHooks(settings, venvPython);
+  registerMcpServer(settings, venvPython);
+  writeSettings(settings);
+
+  log("  + Verifying installation...");
+  try {
+    run(`"${venvPython}" -c "from agent_gate.server import create_mcp; print('OK')"`);
+    log("  + Verification passed");
+  } catch {
+    log("  ! Verification failed (install may still work after restart)");
+  }
+
+  log(`
+agent-gate installed successfully
+
+  Location:  ~/.claude/agent-gate/
+  Python:    ${python.full} (${python.version})
+  Venv:      ~/.claude/agent-gate/.venv/
+  Hooks:     3 merged into settings.json
+  MCP:       agent-gate registered
+
+  Restart Claude Code to activate.
+`);
+}
+
+function uninstall() {
+  log("Uninstalling agent-gate...\n");
+
+  if (existsSync(INSTALL_DIR)) {
+    if (!nonInteractive) {
+      log(`  This will delete ${INSTALL_DIR}`);
+      log("  Run with --non-interactive to skip this confirmation.");
+    }
+    rmSync(INSTALL_DIR, { recursive: true, force: true });
+    log("  - Removed ~/.claude/agent-gate/");
+  } else {
+    log("  ~ agent-gate directory not found (already removed?)");
+  }
+
+  const settings = readSettings();
+
+  if (settings.hooks) {
+    for (const eventName of Object.keys(settings.hooks)) {
+      settings.hooks[eventName] = settings.hooks[eventName].filter(
+        (group) => !HOOK_FILENAMES.some((filename) => hookCommandContains(group, filename))
+      );
+      if (settings.hooks[eventName].length === 0) {
+        delete settings.hooks[eventName];
+      }
+    }
+    log("  - Removed agent-gate hooks from settings.json");
+  }
+
+  if (settings.mcpServers?.["agent-gate"]) {
+    delete settings.mcpServers["agent-gate"];
+    log("  - Removed agent-gate MCP server from settings.json");
+  }
+
+  writeSettings(settings);
+  log("\nagent-gate uninstalled. Restart Claude Code.");
+}
+
+function update() {
+  log("Updating agent-gate...\n");
+
+  if (!existsSync(join(INSTALL_DIR, ".git"))) {
+    log("Error: agent-gate is not installed. Run the installer first.");
+    process.exit(1);
+  }
+
+  try {
+    run(`git -C "${INSTALL_DIR}" pull`);
+    log("  + Pulled latest changes");
+  } catch {
+    log("Error: git pull failed.");
+    process.exit(1);
+  }
+
+  const venvPython = getVenvPython(join(INSTALL_DIR, ".venv"));
+  const packagePaths = [
+    join(INSTALL_DIR, "packages", "agent-gate-core"),
+    join(INSTALL_DIR, "packages", "agent-gate-claude"),
+    join(INSTALL_DIR, "packages", "agent-gate-prompt-refinement"),
+    INSTALL_DIR,
+  ];
+  const editableArgs = packagePaths.map((each_path) => `-e "${each_path}"`).join(" ");
+  try {
+    run(`"${venvPython}" -m pip install ${editableArgs}`);
+    log("  + Reinstalled packages");
+  } catch {
+    log("Error: pip install failed.");
+    process.exit(1);
+  }
+
+  log("\nagent-gate updated. Restart Claude Code.");
+}
+
+function printHelp() {
+  log(`
+agent-gate-installer
+
+  One-command setup for the agent-gate prompt evaluation gate.
+
+Usage:
+  npx agent-gate-installer              Install agent-gate
+  npx agent-gate-installer --update     Pull latest and reinstall
+  npx agent-gate-installer --uninstall  Remove agent-gate
+  npx agent-gate-installer --help       Show this help
+
+Flags:
+  --verbose          Show detailed output from each step
+  --non-interactive  Fail if GH_TOKEN is missing (for automation)
+
+Environment:
+  GH_TOKEN           GitHub personal access token (required for private repo)
+
+Prerequisites:
+  - Node.js 18+
+  - Python 3.12+
+  - git
+`);
+}
+
+if (flags.has("--help") || flags.has("-h")) {
+  printHelp();
+} else if (flags.has("--uninstall")) {
+  uninstall();
+} else if (flags.has("--update")) {
+  update();
+} else {
+  install();
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "agent-gate-installer",
+  "version": "1.0.0",
+  "description": "One-command installer for agent-gate prompt evaluation gate",
+  "type": "module",
+  "bin": {
+    "agent-gate-installer": "./bin/install.mjs"
+  },
+  "files": [
+    "bin/"
+  ],
+  "keywords": [
+    "claude-code",
+    "agent-gate",
+    "prompt-gate",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jl-cmd/agent-gate.git"
+  }
+}