@misterhuydo/sentinel 1.0.0

package/bin/sentinel.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+const chalk = require('chalk');
+const [,, command = 'help', ...args] = process.argv;
+
+const BANNER = `
+${chalk.cyan('███████╗███████╗███╗   ██╗████████╗██╗███╗   ██╗███████╗██╗')}
+${chalk.cyan('██╔════╝██╔════╝████╗  ██║╚══██╔══╝██║████╗  ██║██╔════╝██║')}
+${chalk.cyan('███████╗█████╗  ██╔██╗ ██║   ██║   ██║██╔██╗ ██║█████╗  ██║')}
+${chalk.cyan('╚════██║██╔══╝  ██║╚██╗██║   ██║   ██║██║╚██╗██║██╔══╝  ██║')}
+${chalk.cyan('███████║███████╗██║ ╚████║   ██║   ██║██║ ╚████║███████╗███████╗')}
+${chalk.cyan('╚══════╝╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝')}
+${chalk.gray('  Autonomous DevOps Agent')}
+`;
+
+async function main() {
+  console.log(BANNER);
+
+  switch (command) {
+    case 'init':
+      await require('../lib/init')();
+      break;
+    case 'add':
+      await require('../lib/add')(args[0]);
+      break;
+    case 'help':
+    default:
+      console.log(`${chalk.bold('Usage:')}
+  sentinel init          Interactive setup — install everything and create workspace
+  sentinel add <name>    Add a new project instance to an existing workspace
+`);
+  }
+}
+
+main().catch(err => {
+  console.error(chalk.red('Error:'), err.message);
+  process.exit(1);
+});

package/lib/add.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const prompts = require('prompts');
+const chalk = require('chalk');
+const { writeExampleProject, generateWorkspaceScripts } = require('./generate');
+
+module.exports = async function add(nameArg) {
+  const answers = await prompts([
+    {
+      type: 'text',
+      name: 'workspace',
+      message: 'Workspace directory',
+      initial: path.join(os.homedir(), 'sentinel'),
+      format: v => v.replace(/^~/, os.homedir()),
+    },
+    {
+      type: 'text',
+      name: 'name',
+      message: 'Project name',
+      initial: nameArg || 'my-project',
+      validate: v => /^[a-z0-9_-]+$/i.test(v) || 'Use letters, numbers, hyphens only',
+    },
+  ], { onCancel: () => process.exit(0) });
+
+  const { workspace, name } = answers;
+  const codeDir = path.join(workspace, 'code');
+  const pythonBin = path.join(codeDir, '.venv', 'bin', 'python3');
+  const projectDir = path.join(workspace, name);
+
+  if (!fs.existsSync(codeDir)) {
+    console.error(chalk.red(`Sentinel code not found at ${codeDir}`));
+    console.error(chalk.red('Run "sentinel init" first.'));
+    process.exit(1);
+  }
+
+  if (fs.existsSync(projectDir)) {
+    console.error(chalk.yellow(`Project "${name}" already exists at ${projectDir}`));
+    process.exit(1);
+  }
+
+  writeExampleProject(projectDir, codeDir, pythonBin);
+  generateWorkspaceScripts(workspace);
+
+  console.log('\n' + chalk.green('✔'), `Project "${name}" created at ${projectDir}`);
+  console.log(`
+  Next steps:
+    1. Edit config files in:
+       ${chalk.cyan(`${projectDir}/config/`)}
+    2. Run first-time init:
+       ${chalk.cyan(`${projectDir}/init.sh`)}
+    3. Start this project:
+       ${chalk.cyan(`${projectDir}/start.sh`)}
+`);
+};

package/lib/generate.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+
+// ── Per-project files ─────────────────────────────────────────────────────────
+
+function writeExampleProject(projectDir, codeDir, pythonBin) {
+  const configDir = path.join(projectDir, 'config', 'log-configs');
+  const repoDir   = path.join(projectDir, 'config', 'repo-configs');
+  fs.ensureDirSync(configDir);
+  fs.ensureDirSync(repoDir);
+
+  // Copy example config templates from bundled python/
+  const tplDir = path.join(__dirname, '..', 'templates');
+  fs.copySync(path.join(tplDir, 'sentinel.properties'),     path.join(projectDir, 'config', 'sentinel.properties'));
+  fs.copySync(path.join(tplDir, 'log-configs', '_example.properties'), path.join(configDir, '_example.properties'));
+  fs.copySync(path.join(tplDir, 'repo-configs', '_example.properties'), path.join(repoDir,   '_example.properties'));
+
+  generateProjectScripts(projectDir, codeDir, pythonBin);
+}
+
+function generateProjectScripts(projectDir, codeDir, pythonBin) {
+  const name = path.basename(projectDir);
+
+  // init.sh
+  fs.writeFileSync(path.join(projectDir, 'init.sh'), `#!/usr/bin/env bash
+# First-time setup: clone repos, test SSH, send test email
+set -euo pipefail
+cd "$(dirname "$0")"
+PYTHONPATH="${codeDir}" "${pythonBin}" -m sentinel.main --config ./config --init
+`, { mode: 0o755 });
+
+  // start.sh
+  fs.writeFileSync(path.join(projectDir, 'start.sh'), `#!/usr/bin/env bash
+# Start this Sentinel instance
+set -euo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+PID_FILE="$DIR/sentinel.pid"
+
+if [[ -f "$PID_FILE" ]] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
+  echo "[sentinel] ${name} already running (PID $(cat "$PID_FILE"))"
+  exit 0
+fi
+
+mkdir -p "$DIR/logs" "$DIR/workspace/fetched" "$DIR/workspace/patches"
+cd "$DIR"
+PYTHONPATH="${codeDir}" "${pythonBin}" -m sentinel.main --config ./config \\
+  >> "$DIR/logs/sentinel.log" 2>&1 &
+echo $! > "$PID_FILE"
+echo "[sentinel] ${name} started (PID $!)"
+`, { mode: 0o755 });
+
+  // stop.sh
+  fs.writeFileSync(path.join(projectDir, 'stop.sh'), `#!/usr/bin/env bash
+# Stop this Sentinel instance
+set -euo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+PID_FILE="$DIR/sentinel.pid"
+
+if [[ ! -f "$PID_FILE" ]]; then
+  echo "[sentinel] ${name} — no PID file, not running"
+  exit 0
+fi
+
+PID=$(cat "$PID_FILE")
+if kill -0 "$PID" 2>/dev/null; then
+  kill "$PID"
+  echo "[sentinel] ${name} stopped (PID $PID)"
+else
+  echo "[sentinel] ${name} — PID $PID not running"
+fi
+rm -f "$PID_FILE"
+`, { mode: 0o755 });
+}
+
+// ── Workspace-level startAll / stopAll ────────────────────────────────────────
+
+function generateWorkspaceScripts(workspace) {
+  // startAll.sh
+  fs.writeFileSync(path.join(workspace, 'startAll.sh'), `#!/usr/bin/env bash
+# Start all Sentinel project instances
+WORKSPACE="$(cd "$(dirname "$0")" && pwd)"
+started=0
+for project_dir in "$WORKSPACE"/*/; do
+  name=$(basename "$project_dir")
+  [[ "$name" == "code" ]] && continue
+  [[ -f "$project_dir/start.sh" ]] || continue
+  bash "$project_dir/start.sh"
+  started=$((started + 1))
+done
+echo "[sentinel] $started project(s) started"
+`, { mode: 0o755 });
+
+  // stopAll.sh
+  fs.writeFileSync(path.join(workspace, 'stopAll.sh'), `#!/usr/bin/env bash
+# Stop all Sentinel project instances
+WORKSPACE="$(cd "$(dirname "$0")" && pwd)"
+stopped=0
+for project_dir in "$WORKSPACE"/*/; do
+  name=$(basename "$project_dir")
+  [[ "$name" == "code" ]] && continue
+  [[ -f "$project_dir/stop.sh" ]] || continue
+  bash "$project_dir/stop.sh"
+  stopped=$((stopped + 1))
+done
+echo "[sentinel] $stopped project(s) stopped"
+`, { mode: 0o755 });
+}
+
+module.exports = { writeExampleProject, generateProjectScripts, generateWorkspaceScripts };

package/lib/init.js

@@ -0,0 +1,206 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const { execSync, spawnSync } = require('child_process');
+const prompts = require('prompts');
+const chalk = require('chalk');
+const { generateProjectScripts, generateWorkspaceScripts, writeExampleProject } = require('./generate');
+
+const ok   = msg => console.log(chalk.green('  ✔'), msg);
+const info = msg => console.log(chalk.cyan('  →'), msg);
+const warn = msg => console.log(chalk.yellow('  ⚠'), msg);
+const step = msg => console.log('\n' + chalk.bold.white(msg));
+
+module.exports = async function init() {
+  // ── Prompts ─────────────────────────────────────────────────────────────────
+  const answers = await prompts([
+    {
+      type: 'text',
+      name: 'workspace',
+      message: 'Workspace directory (each project lives here as a subdirectory)',
+      initial: path.join(os.homedir(), 'sentinel'),
+      format: v => v.replace(/^~/, os.homedir()),
+    },
+    {
+      type: 'confirm',
+      name: 'example',
+      message: 'Create an example project to show how to configure?',
+      initial: true,
+    },
+    {
+      type: 'confirm',
+      name: 'systemd',
+      message: 'Set up systemd service for auto-start on reboot?',
+      initial: process.platform === 'linux',
+    },
+  ], { onCancel: () => process.exit(0) });
+
+  const { workspace, example, systemd } = answers;
+  const codeDir = path.join(workspace, 'code');
+
+  // ── Python ──────────────────────────────────────────────────────────────────
+  step('Checking Python…');
+  const python = findPython();
+  if (!python) {
+    console.error(chalk.red('  ✖ python3 not found. Install it first:'));
+    console.error('      sudo apt-get install -y python3 python3-pip python3-venv');
+    process.exit(1);
+  }
+  ok(`Python: ${run(python, ['--version']).trim()}`);
+
+  // ── Copy Sentinel Python source ─────────────────────────────────────────────
+  step('Installing Sentinel code…');
+  const bundledPython = path.join(__dirname, '..', 'python');
+  if (!fs.existsSync(bundledPython)) {
+    console.error(chalk.red('  ✖ Bundled Python source not found (run npm publish from the Sentinel repo)'));
+    process.exit(1);
+  }
+  fs.ensureDirSync(codeDir);
+  fs.copySync(bundledPython, codeDir, { overwrite: true });
+  ok(`Sentinel code → ${codeDir}`);
+
+  // ── Python venv ─────────────────────────────────────────────────────────────
+  step('Setting up Python environment…');
+  const venv = path.join(codeDir, '.venv');
+  if (!fs.existsSync(venv)) {
+    info('Creating virtual environment…');
+    runLive(python, ['-m', 'venv', venv]);
+  }
+  const pip = path.join(venv, 'bin', 'pip3');
+  const pythonBin = path.join(venv, 'bin', 'python3');
+  info('Installing Python packages…');
+  runLive(pip, ['install', '--quiet', '--upgrade', 'pip']);
+  runLive(pip, ['install', '--quiet', '-r', path.join(codeDir, 'requirements.txt')]);
+  ok('Python packages installed');
+
+  // ── Node tools ──────────────────────────────────────────────────────────────
+  step('Installing Node tools…');
+  installNpmGlobal('@misterhuydo/cairn-mcp', 'cairn');
+  installNpmGlobal('@anthropic-ai/claude-code', 'claude');
+
+  // ── Workspace structure ─────────────────────────────────────────────────────
+  step('Creating workspace…');
+  fs.ensureDirSync(workspace);
+  ok(`Workspace: ${workspace}`);
+
+  // ── Example project ─────────────────────────────────────────────────────────
+  if (example) {
+    step('Creating example project…');
+    const exampleDir = path.join(workspace, 'my-project');
+    writeExampleProject(exampleDir, codeDir, pythonBin);
+    ok(`Example project: ${exampleDir}`);
+  }
+
+  // ── Workspace start/stop scripts ─────────────────────────────────────────────
+  step('Generating scripts…');
+  generateWorkspaceScripts(workspace);
+  ok(`${workspace}/startAll.sh`);
+  ok(`${workspace}/stopAll.sh`);
+
+  // ── systemd ──────────────────────────────────────────────────────────────────
+  if (systemd) {
+    step('Setting up systemd…');
+    setupSystemd(workspace);
+  }
+
+  // ── Done ─────────────────────────────────────────────────────────────────────
+  console.log('\n' + chalk.bold.green('══ Done! ══') + '\n');
+  console.log(`${chalk.bold('Next steps:')}`);
+  if (example) {
+    console.log(`
+  1. Configure your first project:
+     ${chalk.cyan(`${workspace}/my-project/config/sentinel.properties`)}
+     ${chalk.cyan(`${workspace}/my-project/config/log-configs/`)}
+     ${chalk.cyan(`${workspace}/my-project/config/repo-configs/`)}
+
+  2. First-time init (clones repos, tests SSH, sends test email):
+     ${chalk.cyan(`${workspace}/my-project/init.sh`)}
+
+  3. Start all projects:
+     ${chalk.cyan(`${workspace}/startAll.sh`)}
+
+  4. Stop all projects:
+     ${chalk.cyan(`${workspace}/stopAll.sh`)}
+`);
+  }
+  if (systemd) {
+    console.log(`  Auto-start is enabled. To manage:
+     ${chalk.cyan('sudo systemctl start sentinel')}
+     ${chalk.cyan('sudo systemctl status sentinel')}
+     ${chalk.cyan('journalctl -u sentinel -f')}
+`);
+  }
+  console.log(`  Add another project anytime:
+     ${chalk.cyan('sentinel add <project-name>')}
+`);
+};
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function findPython() {
+  for (const bin of ['python3', 'python']) {
+    try {
+      execSync(`${bin} --version`, { stdio: 'pipe' });
+      return bin;
+    } catch (_) {}
+  }
+  return null;
+}
+
+function run(bin, args) {
+  const r = spawnSync(bin, args, { encoding: 'utf8' });
+  return (r.stdout || '') + (r.stderr || '');
+}
+
+function runLive(bin, args) {
+  const r = spawnSync(bin, args, { stdio: 'inherit' });
+  if (r.status !== 0) {
+    console.error(chalk.red(`  ✖ Command failed: ${bin} ${args.join(' ')}`));
+    process.exit(1);
+  }
+}
+
+function installNpmGlobal(pkg, checkBin) {
+  try {
+    execSync(`${checkBin} --version`, { stdio: 'pipe' });
+    ok(`${pkg} already installed`);
+  } catch (_) {
+    info(`Installing ${pkg}…`);
+    runLive('npm', ['install', '-g', pkg]);
+    ok(`${pkg} installed`);
+  }
+}
+
+function setupSystemd(workspace) {
+  const user = os.userInfo().username;
+  const svc = `/etc/systemd/system/sentinel.service`;
+  const content = `[Unit]
+Description=Sentinel — Autonomous DevOps Agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=forking
+User=${user}
+WorkingDirectory=${workspace}
+ExecStart=${workspace}/startAll.sh
+ExecStop=${workspace}/stopAll.sh
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+`;
+  try {
+    fs.writeFileSync('/tmp/sentinel.service', content);
+    execSync(`sudo mv /tmp/sentinel.service ${svc}`);
+    execSync('sudo systemctl daemon-reload');
+    execSync('sudo systemctl enable sentinel');
+    ok('sentinel.service enabled');
+  } catch (e) {
+    warn(`Could not write systemd service (need sudo): ${e.message}`);
+    warn(`Manually create ${svc} to auto-start on reboot`);
+  }
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@misterhuydo/sentinel",
+  "version": "1.0.0",
+  "description": "Sentinel — Autonomous DevOps Agent installer and manager",
+  "bin": {
+    "sentinel": "./bin/sentinel.js"
+  },
+  "scripts": {
+    "prepublishOnly": "node scripts/bundle.js"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "fs-extra": "^11.2.0",
+    "prompts": "^2.4.2"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "author": "misterhuydo",
+  "license": "MIT"
+}

package/python/requirements.txt

@@ -0,0 +1,5 @@
+paramiko>=3.4
+schedule>=1.2
+python-dotenv>=1.0
+requests>=2.31
+jinja2>=3.1

package/python/sentinel/cairn_client.py

@@ -0,0 +1,45 @@
+"""
+cairn_client.py — Cairn MCP integration.
+
+Cairn is a passive MCP tool: when properly installed and configured in Claude
+Code's MCP settings, it is used automatically by Claude during fix generation.
+Sentinel's only responsibility is to pre-index repos at startup so the index
+exists before the first fix attempt.
+
+Install: npm install -g @misterhuydo/cairn-mcp
+"""
+
+import logging
+import subprocess
+
+from .config_loader import RepoConfig
+
+logger = logging.getLogger(__name__)
+
+CAIRN_BIN = "cairn"
+
+
+def ensure_installed() -> bool:
+    try:
+        r = subprocess.run([CAIRN_BIN, "--version"], capture_output=True, text=True, timeout=10)
+        if r.returncode == 0:
+            logger.debug("Cairn version: %s", r.stdout.strip())
+            return True
+    except FileNotFoundError:
+        pass
+    logger.error("Cairn not found. Run: npm install -g @misterhuydo/cairn-mcp")
+    return False
+
+
+def index_repo(repo: RepoConfig) -> bool:
+    """Index a repo so Cairn context is available for Claude Code. Run at --init."""
+    logger.info("Indexing %s with Cairn...", repo.repo_name)
+    r = subprocess.run(
+        [CAIRN_BIN, "index", "--path", repo.local_path],
+        capture_output=True, text=True, timeout=300,
+    )
+    if r.returncode != 0:
+        logger.error("Cairn index failed for %s:\n%s", repo.repo_name, r.stderr)
+        return False
+    logger.info("Cairn index complete for %s", repo.repo_name)
+    return True

package/python/sentinel/cicd_trigger.py

@@ -0,0 +1,66 @@
+"""
+cicd_trigger.py — Trigger CI/CD pipelines after a successful push.
+
+Only used when AUTO_PUBLISH=true. For AUTO_PUBLISH=false, CI/CD is
+triggered by the normal GitHub merge webhook.
+"""
+
+import logging
+
+import requests
+
+from .config_loader import RepoConfig
+from .state_store import StateStore
+
+logger = logging.getLogger(__name__)
+
+
+def trigger(repo: RepoConfig, store: StateStore, fingerprint: str) -> bool:
+    if not repo.cicd_type or not repo.cicd_job_url:
+        return True
+
+    cicd_type = repo.cicd_type.lower()
+    if cicd_type == "jenkins":
+        return _trigger_jenkins(repo)
+    elif cicd_type in ("github_actions", "github-actions"):
+        return _trigger_github_actions(repo, fingerprint)
+    else:
+        logger.warning("Unknown CICD_TYPE '%s' for %s", repo.cicd_type, repo.repo_name)
+        return False
+
+
+def _trigger_jenkins(repo: RepoConfig) -> bool:
+    url = f"{repo.cicd_job_url.rstrip('/')}/build"
+    resp = requests.post(url, auth=("sentinel", repo.cicd_token), timeout=15)
+    success = resp.status_code in (200, 201, 204)
+    if success:
+        logger.info("Jenkins triggered: %s", repo.cicd_job_url)
+    else:
+        logger.error("Jenkins trigger failed (%s): %s", resp.status_code, resp.text[:200])
+    return success
+
+
+def _trigger_github_actions(repo: RepoConfig, fingerprint: str) -> bool:
+    owner_repo = _owner_repo(repo.repo_url)
+    url = f"https://api.github.com/repos/{owner_repo}/dispatches"
+    resp = requests.post(
+        url,
+        json={"event_type": "sentinel-deploy", "client_payload": {"fingerprint": fingerprint}},
+        headers={
+            "Authorization": f"Bearer {repo.cicd_token}",
+            "Accept": "application/vnd.github+json",
+        },
+        timeout=15,
+    )
+    success = resp.status_code == 204
+    if success:
+        logger.info("GitHub Actions dispatch sent for %s", owner_repo)
+    else:
+        logger.error("GH Actions dispatch failed (%s): %s", resp.status_code, resp.text[:200])
+    return success
+
+
+def _owner_repo(repo_url: str) -> str:
+    if repo_url.startswith("git@"):
+        return repo_url.split(":")[-1].removesuffix(".git")
+    return "/".join(repo_url.rstrip("/").split("/")[-2:]).removesuffix(".git")