petadep 1.0.1

package/README.md

@@ -0,0 +1,78 @@
+# petadep
+
+Deploy GitHub repos to a VPS on push via GitHub webhooks or a GitHub App.
+
+## Install
+
+```bash
+npm install
+```
+
+Make the CLI executable:
+
+```bash
+chmod +x bin/petadep.js
+```
+
+## Initialize config
+
+```bash
+petadep init --config ./data/config.json
+```
+
+This creates `./data/config.json`, `./data/`, and `./logs/`, prints the webhook secret, and shows the next step.
+
+## Add a deployment target
+
+```bash
+petadep add --config ./data/config.json \
+  --repo owner/repo \
+  --branch staging \
+  --env staging \
+  --workdir /var/www/repo-staging \
+  --script ./deploy/staging.sh
+```
+
+## Run the agent
+
+```bash
+petadep agent --config ./data/config.json
+```
+
+The server exposes:
+
+- `POST /webhook` (or `config.path`)
+- `GET /health`
+
+## GitHub webhook setup
+
+- **Webhook URL**: `http://YOUR_VPS_IP:8787/webhook` (match `config.path`)
+- **Secret**: the value printed by `init` (also stored in the config)
+- **Events**: `push` (or update `security.allowedEvents`)
+
+If using a GitHub App, set the same URL/secret in the App's webhook settings.
+
+## SSH deploy key requirement
+
+The agent clones via SSH using `git@github.com:owner/repo.git`. Your VPS must have a deploy key or SSH key with access to the repo. Add the VPS public key as a **Deploy key** in GitHub (read-only is fine).
+
+## Config schema
+
+```json
+{
+  "port": 8787,
+  "path": "/webhook",
+  "secret": "<random>",
+  "deployments": [
+    {
+      "repo": "owner/repo",
+      "branch": "staging",
+      "env": "staging",
+      "workdir": "/var/www/repo-staging",
+      "script": "./deploy/staging.sh"
+    }
+  ],
+  "security": { "allowedEvents": ["push"], "lockPerTarget": true, "timeoutSeconds": 900 },
+  "logsDir": "./logs"
+}
+```

package/bin/petadep.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { initConfig, addDeployment } from "../src/cli.js";
+import { startAgent } from "../src/agent.js";
+
+async function main() {
+  yargs(hideBin(process.argv))
+    .scriptName("petadep")
+    .command(
+      "init",
+      "Initialize a config file",
+      (y) =>
+        y.option("config", {
+          type: "string",
+          demandOption: true,
+          describe: "Path to config JSON",
+        }),
+      async (argv) => {
+        await initConfig({ configPath: argv.config });
+      }
+    )
+    .command(
+      "add",
+      "Add a deployment target",
+      (y) =>
+        y
+          .option("config", {
+            type: "string",
+            demandOption: true,
+            describe: "Path to config JSON",
+          })
+          .option("repo", {
+            type: "string",
+            demandOption: true,
+            describe: "Repo in owner/repo format",
+          })
+          .option("branch", {
+            type: "string",
+            demandOption: true,
+            describe: "Branch name",
+          })
+          .option("env", {
+            type: "string",
+            demandOption: true,
+            describe: "Environment name",
+          })
+          .option("workdir", {
+            type: "string",
+            demandOption: true,
+            describe: "Working directory on the VPS",
+          })
+          .option("script", {
+            type: "string",
+            demandOption: true,
+            describe: "Deploy script path (relative to repo or absolute)",
+          }),
+      async (argv) => {
+        await addDeployment({
+          configPath: argv.config,
+          repo: argv.repo,
+          branch: argv.branch,
+          env: argv.env,
+          workdir: argv.workdir,
+          script: argv.script,
+        });
+      }
+    )
+    .command(
+      "agent",
+      "Start the webhook server",
+      (y) =>
+        y.option("config", {
+          type: "string",
+          demandOption: true,
+          describe: "Path to config JSON",
+        }),
+      async (argv) => {
+        await startAgent({ configPath: argv.config });
+      }
+    )
+    .demandCommand(1, "Choose a command")
+    .strict()
+    .help()
+    .parse();
+}
+
+main().catch((err) => {
+  console.error(err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "petadep",
+  "version": "1.0.1",
+  "description": "Deploy GitHub repos to a VPS on push via webhooks",
+  "type": "module",
+  "bin": {
+    "petadep": "./bin/petadep.js"
+  },
+  "main": "./src/agent.js",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "start": "node bin/petadep.js agent --config ./data/config.json",
+    "dev": "nodemon --exec node bin/petadep.js agent --config ./data/config.json"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "dotenv": "^17.2.3",
+    "execa": "^9.6.1",
+    "express": "^5.2.1",
+    "yargs": "^18.0.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.11"
+  }
+}

package/src/agent.js

@@ -0,0 +1,113 @@
+import fs from "fs/promises";
+import path from "path";
+import express from "express";
+import dotenv from "dotenv";
+import { z } from "zod";
+import { verifyGithubSignature } from "./verifyGithub.js";
+import { deployTarget } from "./deployer.js";
+import { appendLog, ensureDir } from "./logger.js";
+
+dotenv.config();
+
+const deploymentSchema = z.object({
+  repo: z.string().min(1),
+  branch: z.string().min(1),
+  env: z.string().min(1),
+  workdir: z.string().min(1),
+  script: z.string().min(1),
+});
+
+const securitySchema = z
+  .object({
+    allowedEvents: z.array(z.string()).default(["push"]),
+    lockPerTarget: z.boolean().default(true),
+    timeoutSeconds: z.coerce.number().int().positive().default(900),
+  })
+  .default({});
+
+const configSchema = z.object({
+  port: z.coerce.number().int().positive().default(8787),
+  path: z.string().default("/webhook"),
+  secret: z.string().min(1),
+  deployments: z.array(deploymentSchema).default([]),
+  security: securitySchema,
+  logsDir: z.string().default("./logs"),
+});
+
+async function loadConfig(configPath) {
+  const resolvedPath = path.resolve(configPath);
+  const raw = await fs.readFile(resolvedPath, "utf8");
+  const parsed = JSON.parse(raw);
+  return configSchema.parse(parsed);
+}
+
+export async function startAgent({ configPath }) {
+  const config = await loadConfig(configPath);
+  await ensureDir(config.logsDir);
+
+  const app = express();
+  app.use(
+    express.json({
+      verify: (req, _res, buf) => {
+        req.rawBody = buf;
+      },
+    })
+  );
+
+  app.get("/health", (_req, res) => {
+    res.json({ status: "ok" });
+  });
+
+  app.post(config.path, async (req, res) => {
+    const event = req.headers["x-github-event"];
+    const signature = req.headers["x-hub-signature-256"];
+    const isValid = verifyGithubSignature({
+      secret: config.secret,
+      rawBody: req.rawBody,
+      signature,
+    });
+
+    if (!isValid) {
+      const securityLog = path.join(config.logsDir, "security.log");
+      const line = `[${new Date().toISOString()}] Invalid signature from ${
+        req.ip
+      }\n`;
+      await appendLog(securityLog, line);
+      return res.status(401).json({ error: "invalid signature" });
+    }
+
+    if (!config.security.allowedEvents.includes(event)) {
+      return res.status(202).json({ status: "ignored", reason: "event" });
+    }
+
+    const repo = req.body?.repository?.full_name;
+    const ref = req.body?.ref;
+    const branch = typeof ref === "string" ? ref.replace("refs/heads/", "") : "";
+
+    if (!repo || !branch) {
+      return res.status(400).json({ error: "missing repo or branch" });
+    }
+
+    const target = config.deployments.find(
+      (d) => d.repo === repo && d.branch === branch
+    );
+    if (!target) {
+      return res.status(202).json({ status: "ignored", reason: "no target" });
+    }
+
+    res.status(202).json({ status: "accepted" });
+
+    setImmediate(() => {
+      deployTarget(target, config).catch(() => {
+        return;
+      });
+    });
+  });
+
+  app.listen(config.port, () => {
+    console.log(
+      `Webhook listening on http://localhost:${config.port}${config.path}`
+    );
+    console.log(`Health check on http://localhost:${config.port}/health`);
+  });
+}

package/src/cli.js

@@ -0,0 +1,65 @@
+import fs from "fs/promises";
+import path from "path";
+import crypto from "crypto";
+
+function defaultConfig(secret) {
+  return {
+    port: 8787,
+    path: "/webhook",
+    secret,
+    deployments: [],
+    security: {
+      allowedEvents: ["push"],
+      lockPerTarget: true,
+      timeoutSeconds: 900,
+    },
+    logsDir: "./logs",
+  };
+}
+
+export async function initConfig({ configPath }) {
+  const resolvedPath = path.resolve(configPath);
+  const configDir = path.dirname(resolvedPath);
+  await fs.mkdir(configDir, { recursive: true });
+  await fs.mkdir(path.resolve("data"), { recursive: true });
+  await fs.mkdir(path.resolve("logs"), { recursive: true });
+
+  const secret = crypto.randomBytes(32).toString("hex");
+  const config = defaultConfig(secret);
+  await fs.writeFile(resolvedPath, JSON.stringify(config, null, 2));
+
+  console.log("Config created:", resolvedPath);
+  console.log("Webhook secret:", secret);
+  console.log(
+    "Next: add a deployment with `petadep add --config " +
+      resolvedPath +
+      " --repo owner/repo --branch main --env production --workdir /var/www/repo --script ./deploy.sh`"
+  );
+}
+
+export async function addDeployment({
+  configPath,
+  repo,
+  branch,
+  env,
+  workdir,
+  script,
+}) {
+  const resolvedPath = path.resolve(configPath);
+  const raw = await fs.readFile(resolvedPath, "utf8");
+  const config = JSON.parse(raw);
+  config.deployments = Array.isArray(config.deployments)
+    ? config.deployments
+    : [];
+
+  const exists = config.deployments.find(
+    (d) => d.repo === repo && d.branch === branch && d.env === env
+  );
+  if (exists) {
+    throw new Error("Deployment already exists for this repo/branch/env.");
+  }
+
+  config.deployments.push({ repo, branch, env, workdir, script });
+  await fs.writeFile(resolvedPath, JSON.stringify(config, null, 2));
+  console.log("Deployment added:", repo, branch, env);
+}

package/src/deployer.js

@@ -0,0 +1,138 @@
+import fs from "fs";
+import fsp from "fs/promises";
+import path from "path";
+import { execa } from "execa";
+import { appendLog, ensureDir } from "./logger.js";
+import { lockPathForTarget, withFileLock } from "./locks.js";
+
+function logPathForTarget(config, target) {
+  const safeRepo = target.repo.replace(/\//g, "__");
+  return path.join(config.logsDir, `${safeRepo}__${target.env}.log`);
+}
+
+function toIsoLine(message) {
+  return `[${new Date().toISOString()}] ${message}\n`;
+}
+
+async function runCommand(command, args, options, logStream) {
+  const child = execa(command, args, options);
+  if (child.stdout) {
+    child.stdout.pipe(logStream, { end: false });
+  }
+  if (child.stderr) {
+    child.stderr.pipe(logStream, { end: false });
+  }
+  await child;
+}
+
+async function ensureRepo(target, config, logStream, timeoutMs) {
+  await fsp.mkdir(target.workdir, { recursive: true });
+  const gitDir = path.join(target.workdir, ".git");
+  const hasGit = fs.existsSync(gitDir);
+
+  if (!hasGit) {
+    const contents = await fsp.readdir(target.workdir);
+    if (contents.length > 0) {
+      throw new Error("Workdir is not empty and is not a git repository.");
+    }
+    const sshUrl = `git@github.com:${target.repo}.git`;
+    await appendLog(
+      logPathForTarget(config, target),
+      toIsoLine(`Cloning ${sshUrl} into ${target.workdir}`)
+    );
+    await runCommand(
+      "git",
+      ["clone", sshUrl, target.workdir],
+      { timeout: timeoutMs },
+      logStream
+    );
+  }
+}
+
+async function checkoutBranch(target, logStream, timeoutMs) {
+  const cwd = target.workdir;
+  await runCommand("git", ["fetch", "--all", "--prune"], { cwd, timeout: timeoutMs }, logStream);
+
+  let hasBranch = true;
+  try {
+    await runCommand(
+      "git",
+      ["rev-parse", "--verify", target.branch],
+      { cwd, timeout: timeoutMs },
+      logStream
+    );
+  } catch {
+    hasBranch = false;
+  }
+
+  if (hasBranch) {
+    await runCommand(
+      "git",
+      ["checkout", target.branch],
+      { cwd, timeout: timeoutMs },
+      logStream
+    );
+  } else {
+    await runCommand(
+      "git",
+      ["checkout", "-b", target.branch, `origin/${target.branch}`],
+      { cwd, timeout: timeoutMs },
+      logStream
+    );
+  }
+
+  await runCommand(
+    "git",
+    ["reset", "--hard", `origin/${target.branch}`],
+    { cwd, timeout: timeoutMs },
+    logStream
+  );
+}
+
+async function runScript(target, logStream, timeoutMs) {
+  const scriptPath = path.isAbsolute(target.script)
+    ? target.script
+    : path.join(target.workdir, target.script);
+  await runCommand("bash", [scriptPath], { cwd: target.workdir, timeout: timeoutMs }, logStream);
+}
+
+export async function deployTarget(target, config) {
+  const logFile = logPathForTarget(config, target);
+  await ensureDir(config.logsDir);
+  await appendLog(logFile, toIsoLine("Deployment starting"));
+
+  const targetId = `${target.repo}__${target.env}`;
+  const lockFile = lockPathForTarget(targetId);
+  const timeoutMs = (config.security?.timeoutSeconds || 900) * 1000;
+
+  const run = async () => {
+    const logStream = fs.createWriteStream(logFile, { flags: "a" });
+    try {
+      await ensureRepo(target, config, logStream, timeoutMs);
+      await checkoutBranch(target, logStream, timeoutMs);
+      await runScript(target, logStream, timeoutMs);
+      await appendLog(logFile, toIsoLine("Deployment finished"));
+    } catch (err) {
+      await appendLog(
+        logFile,
+        toIsoLine(`Deployment failed: ${err?.message || err}`)
+      );
+      throw err;
+    } finally {
+      logStream.end();
+    }
+  };
+
+  if (config.security?.lockPerTarget !== false) {
+    try {
+      return await withFileLock(lockFile, run);
+    } catch (err) {
+      await appendLog(
+        logFile,
+        toIsoLine(`Deployment skipped: ${err?.message || err}`)
+      );
+      throw err;
+    }
+  }
+  return run();
+}

package/src/locks.js

@@ -0,0 +1,32 @@
+import fs from "fs/promises";
+import path from "path";
+
+const LOCK_ROOT = "/tmp";
+
+function sanitize(name) {
+  return name.replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+
+export function lockPathForTarget(targetId) {
+  return path.join(LOCK_ROOT, `${sanitize(targetId)}.lock`);
+}
+
+export async function withFileLock(lockFile, fn) {
+  let handle;
+  try {
+    await fs.mkdir(path.dirname(lockFile), { recursive: true });
+    handle = await fs.open(lockFile, "wx");
+  } catch (err) {
+    if (err && err.code === "EEXIST") {
+      throw new Error("Deployment already running for this target.");
+    }
+    throw err;
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await handle.close();
+    await fs.unlink(lockFile).catch(() => {});
+  }
+}

package/src/logger.js

@@ -0,0 +1,11 @@
+import fs from "fs/promises";
+import path from "path";
+
+export async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+export async function appendLog(filePath, line) {
+  await ensureDir(path.dirname(filePath));
+  await fs.appendFile(filePath, line);
+}

package/src/verifyGithub.js

@@ -0,0 +1,18 @@
+import crypto from "crypto";
+
+export function verifyGithubSignature({ secret, rawBody, signature }) {
+  if (!secret || !rawBody || !signature) {
+    return false;
+  }
+
+  const hmac = crypto.createHmac("sha256", secret);
+  hmac.update(rawBody);
+  const digest = `sha256=${hmac.digest("hex")}`;
+
+  const a = Buffer.from(digest, "utf8");
+  const b = Buffer.from(signature, "utf8");
+  if (a.length !== b.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(a, b);
+}