sentinel-gateway 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# 🛡️ Sentinel
+
+### **The Deterministic Development Gateway**
+*Stop chasing "ghost bugs" and start building with Peer-to-Peer Environment Confidence.*
+
+---
+
+## 🚀 Why Sentinel?
+
+Modern peer-to-peer development (collaborating across different machines) suffers from **"Environment Decay."** Developers pull code but forget to update dependencies, sync `.env` files, or match Node versions. This leads to hours of wasted engineering time debugging issues that aren't in the code, but in the environment.
+
+**Sentinel is a local pre-flight orchestrator.** It sits between you and your application, ensuring your environment is computationally valid before execution. If the environment is broken, Sentinel fixes it. If it’s risky, Sentinel warns you.
+
+---
+
+## ✨ Key Features for Peer-to-Peer Flow
+
+### 🚧 **The Gatekeeper (Version Enforcement)**
+Never worry about a peer using a different Node or NPM version. Sentinel strictly validates system versions against `package.json` engines before allowing execution.
+
+### 📦 **The Auditor (Dependency Sync)**
+Uses a high-performance **Worker Thread** hashing system to compare your local state against the project's lockfile. If a peer added a package, Sentinel detects the mismatch and triggers an auto-install before your server even starts.
+
+### 🔐 **The Warden (Environment Security)**
+Sentinel audits your `.env` against the project's `.env.example`.
+*   **Interactive Provisioning**: If a peer added a new variable, Sentinel prompts you for the value and updates your `.env` automatically.
+*   **Secret Detection**: Warns you if you’ve accidentally hardcoded sensitive keys (AWS, Private Keys) locally.
+
+### 🧹 **The Manager (Clean Slate Porting)**
+Tired of "Port 3000 is already in use"? Sentinel identifies the specific process blocking your dev server and offers an interactive **"Kill & Rebind"** to clear the path.
+
+### 🤖 **CI/CD Fail-Hard Mode**
+Sentinel automatically detects non-interactive terminals. It ensures that your CI pipelines fail immediately if the environment is invalid, preventing hanging builds or mystery failures in production.
+
+---
+
+## 🛠️ Usage
+
+### Installation
+Sentinel is built to be used as a global CLI tool during development.
+
+```bash
+# Clone the repository
+git clone https://github.com/direakanbi/sentinel.git
+cd sentinel
+
+# Build and link globally
+npm install
+npm run build
+npm link
+```
+
+### Running your project
+Replace your standard `npm run dev` with `sentinel`:
+
+```bash
+# Sentinel will orchestrate pre-flight checks and then spawn your dev server
+sentinel dev
+```
+
+---
+
+## 🏗️ Architecture
+
+Sentinel is built with a focus on performance and reliability:
+*   **TypeScript 5.x**: For robust, type-safe orchestration.
+*   **Worker Threads**: Critical path hashing is parallelized to keep pre-flight checks under **1.5s**.
+*   **TDD First**: covered by 30+ integration tests ensuring fail-safe execution.
+
+---
+
+## 🤝 Contributing to Peer-to-Peer Determinism
+
+We believe development should be predictable. If you have ideas for new pre-flight checks (Docker, Python, System Env), feel free to open a PR!
+
+---
+
+*“Sentinel: Because your code is only as good as the environment it runs on.”*

package/dist/auditor/worker.js

@@ -0,0 +1,17 @@
+// src/auditor/worker.ts
+import { parentPort, workerData } from "worker_threads";
+import { createHash } from "crypto";
+import fs from "fs";
+if (parentPort && workerData) {
+  const { files } = workerData;
+  const hashes = {};
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file);
+      const hash = createHash("sha256").update(content).digest("hex");
+      hashes[file] = hash;
+    } catch {
+    }
+  }
+  parentPort.postMessage(hashes);
+}

package/dist/index.js

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/orchestrator.ts
+import { execa as execa3 } from "execa";
+import fs5 from "fs/promises";
+import path5 from "path";
+import chalk from "chalk";
+import enquirer2 from "enquirer";
+
+// src/gatekeeper/system.ts
+import { execa } from "execa";
+async function getSystemVersion(name) {
+  try {
+    const { stdout } = await execa(name, ["--version"]);
+    return stdout.trim();
+  } catch (error) {
+    throw new Error(`Failed to get version for ${name}. Is it installed?`);
+  }
+}
+
+// src/gatekeeper/version.ts
+import semver from "semver";
+function validateVersion(name, requiredRange, actualVersion) {
+  const coercedVersion = semver.coerce(actualVersion)?.version || actualVersion;
+  const satisfied = semver.satisfies(coercedVersion, requiredRange);
+  return {
+    name,
+    satisfied,
+    required: requiredRange,
+    actual: coercedVersion
+  };
+}
+
+// src/gatekeeper/validator.ts
+async function validateEngines(engines) {
+  const componentNames = Object.keys(engines);
+  const results = await Promise.all(
+    componentNames.map(async (name) => {
+      try {
+        const requiredRange = engines[name];
+        const actualVersion = await getSystemVersion(name);
+        return validateVersion(name, requiredRange, actualVersion);
+      } catch (error) {
+        return {
+          name,
+          satisfied: false,
+          required: engines[name],
+          actual: "not found"
+        };
+      }
+    })
+  );
+  return results;
+}
+
+// src/auditor/worker-client.ts
+import { Worker } from "worker_threads";
+import { fileURLToPath } from "url";
+import path from "path";
+import fs from "fs";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+async function runHashingWorker(files) {
+  return new Promise((resolve, reject) => {
+    const isTs = import.meta.url.endsWith(".ts") || process.env.VITEST;
+    let workerPath = path.resolve(__dirname, isTs ? "worker.ts" : "worker.js");
+    if (!isTs && !fs.existsSync(workerPath)) {
+      workerPath = path.resolve(__dirname, "auditor", "worker.js");
+    }
+    if (!isTs && !fs.existsSync(workerPath)) {
+      workerPath = path.resolve(__dirname, "worker.js");
+    }
+    const worker = new Worker(workerPath, {
+      workerData: { files },
+      execArgv: isTs ? ["--import", "tsx"] : []
+    });
+    worker.on("message", resolve);
+    worker.on("error", reject);
+    worker.on("exit", (code) => {
+      if (code !== 0) reject(new Error(`Worker stopped with exit code ${code}`));
+    });
+  });
+}
+
+// src/auditor/sync.ts
+import fs2 from "fs/promises";
+import path2 from "path";
+async function checkSyncStatus(cwd, currentHashes) {
+  const cacheDir = path2.join(cwd, ".sentinel");
+  const cachePath = path2.join(cacheDir, "cache.json");
+  try {
+    const data = await fs2.readFile(cachePath, "utf-8");
+    const cachedHashes = JSON.parse(data);
+    for (const [file, hash] of Object.entries(currentHashes)) {
+      if (cachedHashes[file] !== hash) {
+        return {
+          needsInstall: true,
+          reason: `Hash mismatch for ${file}`,
+          cachedHashes
+        };
+      }
+    }
+    return { needsInstall: false, cachedHashes };
+  } catch (error) {
+    return {
+      needsInstall: true,
+      reason: "No cache found or cache corrupted"
+    };
+  }
+}
+async function updateCache(cwd, hashes) {
+  const cacheDir = path2.join(cwd, ".sentinel");
+  const cachePath = path2.join(cacheDir, "cache.json");
+  await fs2.mkdir(cacheDir, { recursive: true });
+  await fs2.writeFile(cachePath, JSON.stringify(hashes, null, 2), "utf-8");
+}
+
+// src/auditor/security.ts
+import { execa as execa2 } from "execa";
+async function runSecurityAudit() {
+  try {
+    const { stdout } = await execa2("npm", ["audit", "--json"]);
+    const report = JSON.parse(stdout);
+    const criticalCount = report.metadata?.vulnerabilities?.critical || 0;
+    const totalCount = Object.values(report.metadata?.vulnerabilities || {}).reduce(
+      (acc, val) => acc + val,
+      0
+    );
+    return {
+      criticalCount,
+      totalCount,
+      isSafe: criticalCount === 0
+    };
+  } catch (error) {
+    if (error && typeof error === "object" && "stdout" in error) {
+      try {
+        const report = JSON.parse(error.stdout);
+        const criticalCount = report.metadata?.vulnerabilities?.critical || 0;
+        return {
+          criticalCount,
+          totalCount: 0,
+          // Simplified for error case
+          isSafe: criticalCount === 0
+        };
+      } catch {
+      }
+    }
+    return {
+      criticalCount: 0,
+      totalCount: 0,
+      isSafe: true
+    };
+  }
+}
+
+// src/warden/warden.ts
+import fs3 from "fs/promises";
+import path3 from "path";
+import dotenv from "dotenv";
+async function checkEnvironment(cwd) {
+  const envPath = path3.join(cwd, ".env");
+  const examplePath = path3.join(cwd, ".env.example");
+  let exampleContent = "";
+  let envContent = "";
+  try {
+    exampleContent = await fs3.readFile(examplePath, "utf-8");
+  } catch {
+    return { missing: [], secrets: [] };
+  }
+  try {
+    envContent = await fs3.readFile(envPath, "utf-8");
+  } catch {
+    const exampleVars2 = Object.keys(dotenv.parse(exampleContent));
+    return { missing: exampleVars2, secrets: [] };
+  }
+  const exampleVars = Object.keys(dotenv.parse(exampleContent));
+  const envVars = Object.keys(dotenv.parse(envContent));
+  const missing = exampleVars.filter((v) => !envVars.includes(v));
+  const secrets = detectSecrets(envContent);
+  return { missing, secrets };
+}
+function detectSecrets(content) {
+  const parsed = dotenv.parse(content);
+  const detections = [];
+  const patterns = [
+    { name: "AWS Key", regex: /AKIA[0-9A-Z]{16}/ },
+    { name: "Private Key", regex: /-----BEGIN/ },
+    { name: "Generic Secret", regex: /secret|password|token|key/i }
+  ];
+  for (const [key, value] of Object.entries(parsed)) {
+    for (const pattern of patterns) {
+      if (pattern.regex.test(key) || pattern.regex.test(value)) {
+        if (pattern.name === "Generic Secret" && !/example|test|mock/i.test(value)) {
+        }
+        if (pattern.name !== "Generic Secret" || key.toLowerCase().includes("secret") && value.length > 5 && !value.includes("example")) {
+          detections.push({ key, type: pattern.name });
+          break;
+        }
+      }
+    }
+  }
+  return detections;
+}
+
+// src/warden/provisioning.ts
+import fs4 from "fs/promises";
+import path4 from "path";
+import enquirer from "enquirer";
+var { Input } = enquirer;
+async function provisionMissingVariables(cwd, missingVars) {
+  const envPath = path4.join(cwd, ".env");
+  for (const key of missingVars) {
+    const prompt = new Input({
+      name: "value",
+      message: `Enter value for ${key}:`
+    });
+    const value = await prompt.run();
+    await fs4.appendFile(envPath, `
+${key}=${value}`);
+  }
+}
+
+// src/manager/manager.ts
+import findProcess from "find-process";
+import fkill from "fkill";
+async function getProcessOnPort(port) {
+  try {
+    const list = await findProcess("port", port);
+    if (list.length > 0) {
+      return {
+        pid: list[0].pid,
+        name: list[0].name
+      };
+    }
+    return null;
+  } catch (error) {
+    return null;
+  }
+}
+async function killProcess(pid) {
+  try {
+    await fkill(pid, { force: true });
+  } catch (error) {
+    throw new Error(`Failed to kill process ${pid}. Might need elevated permissions.`);
+  }
+}
+
+// src/utils/ci.ts
+import isInteractive from "is-interactive";
+function isNonInteractive() {
+  if (process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true") {
+    return true;
+  }
+  return !isInteractive();
+}
+
+// src/utils/port-detect.ts
+function detectTargetPort(pkg) {
+  if (process.env.PORT) {
+    const port = parseInt(process.env.PORT, 10);
+    if (!isNaN(port)) return port;
+  }
+  const scripts = pkg.scripts || {};
+  const scriptValues = Object.values(scripts).join(" ");
+  const portEnvMatch = scriptValues.match(/PORT=(\d+)/);
+  if (portEnvMatch) {
+    return parseInt(portEnvMatch[1], 10);
+  }
+  const portFlagMatch = scriptValues.match(/(?:--port|-p)\s+(\d+)/);
+  if (portFlagMatch) {
+    return parseInt(portFlagMatch[1], 10);
+  }
+  return 3e3;
+}
+
+// src/orchestrator.ts
+var { Confirm } = enquirer2;
+async function runSentinel(args) {
+  const cwd = process.cwd();
+  const isCI = isNonInteractive();
+  console.log(chalk.cyan("\u{1F6E1}\uFE0F  Sentinel: Starting pre-flight sequence..."));
+  if (isCI) console.log(chalk.dim("Detected non-interactive/CI environment. Pre-flight will fail-hard on all issues."));
+  const pkgPath = path5.join(cwd, "package.json");
+  let pkg;
+  try {
+    const pkgData = await fs5.readFile(pkgPath, "utf-8");
+    pkg = JSON.parse(pkgData);
+  } catch {
+    throw new Error("Could not find package.json in the current directory.");
+  }
+  const startTime = Date.now();
+  const existingLockfiles = [];
+  for (const f of ["package-lock.json", "pnpm-lock.yaml", "yarn.lock"]) {
+    try {
+      await fs5.access(path5.join(cwd, f));
+      existingLockfiles.push(path5.join(cwd, f));
+    } catch {
+    }
+  }
+  const port = detectTargetPort(pkg);
+  const [engineResults, currentHashes, envStatus, processOnPort, securityAudit] = await Promise.all([
+    validateEngines(pkg.engines || {}),
+    existingLockfiles.length > 0 ? runHashingWorker(existingLockfiles) : Promise.resolve({}),
+    checkEnvironment(cwd),
+    getProcessOnPort(port),
+    runSecurityAudit()
+  ]);
+  const failedEngines = engineResults.filter((r) => !r.satisfied);
+  if (failedEngines.length > 0) {
+    console.error(chalk.red("\n\u274C Version requirements not met:"));
+    failedEngines.forEach((r) => console.error(`  - ${r.name}: required ${r.required}, found ${r.actual}`));
+    throw new Error("Version requirements not met");
+  }
+  if (!securityAudit.isSafe) {
+    console.warn(chalk.red(`
+\u{1F6E1}\uFE0F  Critical Security Alert: Found ${securityAudit.criticalCount} critical vulnerabilities.`));
+    if (isCI) {
+      throw new Error("CI Mode: Failing due to critical vulnerabilities.");
+    }
+  }
+  if (envStatus.missing.length > 0) {
+    if (isCI) {
+      throw new Error(`CI Mode: Missing environment variables: ${envStatus.missing.join(", ")}`);
+    }
+    console.log(chalk.yellow(`
+\u26A0\uFE0F  Missing environment variables: ${envStatus.missing.join(", ")}`));
+    await provisionMissingVariables(cwd, envStatus.missing);
+  }
+  if (envStatus.secrets.length > 0) {
+    console.warn(chalk.red(`
+\u{1F6E1}\uFE0F  Security Risk: Potential hardcoded secrets found in .env`));
+    envStatus.secrets.forEach((s) => console.warn(`  - [${s.type}] in ${s.key}`));
+  }
+  if (processOnPort) {
+    console.log(chalk.red(`
+\u{1F6AB} Port ${port} is occupied by ${processOnPort.name} (PID: ${processOnPort.pid})`));
+    if (isCI) {
+      throw new Error("CI Mode: Port occupied. Failing-hard.");
+    }
+    const prompt = new Confirm({
+      name: "kill",
+      message: `Would you like to kill process ${processOnPort.name} and continue?`
+    });
+    if (await prompt.run()) {
+      console.log(chalk.dim(`Killing process ${processOnPort.pid}...`));
+      await killProcess(processOnPort.pid);
+    } else {
+      throw new Error("Port remains occupied. Exiting.");
+    }
+  }
+  const syncStatus = await checkSyncStatus(cwd, currentHashes);
+  if (syncStatus.needsInstall) {
+    console.log(chalk.yellow(`
+\u{1F4E6} Dependencies out of sync: ${syncStatus.reason}`));
+    const pm = pkg.engines?.pnpm ? "pnpm" : pkg.engines?.yarn ? "yarn" : "npm";
+    console.log(chalk.dim(`Running ${pm} install...`));
+    await execa3(pm, ["install"], { stdio: "inherit" });
+    await updateCache(cwd, currentHashes);
+  }
+  const duration = (Date.now() - startTime) / 1e3;
+  console.log(chalk.green(`
+\u2728 Pre-flight successful! (took ${duration.toFixed(2)}s)`));
+  if (args.length > 0) {
+    const [command, ...cmdArgs] = args;
+    await execa3(command, cmdArgs, { stdio: "inherit" });
+  }
+}
+
+// src/index.ts
+import chalk2 from "chalk";
+var program = new Command();
+program.name("sentinel").description("The Deterministic Development Gateway").version("1.0.0");
+program.command("dev", { isDefault: true }).description("Run the development server with pre-flight checks").argument("[args...]", "Arguments to pass to the dev server (default: npm run dev)").action(async (args) => {
+  try {
+    const targetArgs = args.length > 0 ? args : ["npm", "run", "dev"];
+    await runSentinel(targetArgs);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(chalk2.red(`
+\u{1F4A5} Fatal Error: ${error.message}`));
+    }
+    process.exit(1);
+  }
+});
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "sentinel-gateway",
+  "version": "1.0.0",
+  "description": "",
+  "type": "module",
+  "scripts": {
+    "dev": "tsup src/index.ts src/auditor/worker.ts --watch --format esm",
+    "build": "tsup src/index.ts src/auditor/worker.ts --format esm --clean",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+
+  "bin": {
+    "sentinel": "./dist/index.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "colorette": "^2.0.20",
+    "commander": "^14.0.3",
+    "dotenv": "^17.4.1",
+    "enquirer": "^2.4.1",
+    "execa": "^9.6.1",
+    "find-process": "^2.1.1",
+    "fkill": "^10.0.3",
+    "get-port": "^7.2.0",
+    "is-interactive": "^2.0.0",
+    "pino": "^10.3.1",
+    "semver": "^7.7.4"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4",
+    "@types/node": "^25.5.2",
+    "@types/semver": "^7.7.1",
+    "@vitest/coverage-v8": "^4.1.4",
+    "tsx": "^4.21.0"
+  }
+}