fundamentum-cli 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# fundamentum-cli
+
+**One command to make your GitHub repo look (and behave) like a pro open-source project.**
+
+[npm](https://www.npmjs.com/package/fundamentum-cli) · [GitHub](https://github.com/jpvelasco/fundamentum)
+
+Fundamentum bootstraps and hardens GitHub repos for OSS collaboration — community health files, branch protection, secret scanning, and starter CI workflows. You bring the code, it brings the polish.
+
+<p align="center">
+  <a href="https://github.com/jpvelasco/fundamentum/actions/workflows/ci.yml"><img src="https://github.com/jpvelasco/fundamentum/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/jpvelasco/fundamentum/releases/latest"><img src="https://img.shields.io/github/v/release/jpvelasco/fundamentum" alt="Release"></a>
+  <a href="https://www.npmjs.com/package/fundamentum-cli"><img src="https://img.shields.io/npm/v/fundamentum-cli" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/fundamentum-cli"><img src="https://img.shields.io/npm/dm/fundamentum-cli" alt="npm downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+</p>
+
+## Install
+
+```bash
+npm install -g fundamentum-cli
+```
+
+Try without a global install:
+
+```bash
+npx fundamentum-cli --version
+npx fundamentum-cli apply OWNER/REPO
+```
+
+Works on **macOS**, **Linux**, and **Windows** — `x64` and `arm64`. Postinstall downloads the matching prebuilt binary from GitHub Releases with embedded SHA-256 verification.
+
+> **npm 9+ / Ubuntu 26+ note:** npm's `allow-scripts` security policy may block the postinstall
+> script, so the binary won't be downloaded at install time. No worries — if `fundamentum` is invoked
+> without a binary present it detects this and downloads automatically. You can also trigger it
+> manually:
+> ```bash
+> node $(npm root -g)/fundamentum-cli/install.js
+> ```
+
+## Quickstart
+
+```bash
+# Harden an existing repo
+fundamentum apply OWNER/REPO
+
+# Create a new repo + harden it in one shot
+fundamentum init OWNER/REPO
+
+# Preview everything before touching anything
+fundamentum --dry-run apply OWNER/REPO
+
+# Apply file changes via a pull request
+fundamentum --pr apply OWNER/REPO
+```
+
+That's it. A repo that went from bare-bones to release-ready in under a minute.
+
+## What you get
+
+- **Community health files** — `CONTRIBUTING.md`, `CODEOWNERS`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, issue + PR templates, `dependabot.yml`
+- **Branch protection** — modern rulesets on `main` (PR-only pushes, CODEOWNERS review, required checks, no force-push)
+- **Security** — secret scanning + push protection, Dependabot alerts, CodeQL
+- **Starter workflows** — CI, coverage, and CodeQL pipelines that work out of the box
+- **Idempotent by design** — re-running is always safe
+
+## Why fundamentum?
+
+| Manual setup | fundamentum |
+|---------------|-------------|
+| 20+ files and settings across 6 GitHub pages | One command |
+| "Which templates does everyone use?" | Opinionated, proven defaults |
+| Copy-paste from another repo, hope it's current | Rendered fresh, version-controlled |
+| "Did I forget CODEOWNERS?" | Full summary table before you apply |
+| Private repo? Pro account? | Graceful fallbacks for free-tier |
+
+Built for solo devs and small teams who want their repos to feel like they were made by someone who cared.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `apply OWNER/REPO` | Harden an existing repo |
+| `init OWNER/REPO` | Create a new repo, then harden it |
+| `--dry-run` | Preview the full plan without applying |
+| `--pr` | Batch file changes into a pull request |
+| `--no-overwrite` | Only add missing files, never touch existing ones |
+
+## Prerequisites
+
+A GitHub token with `repo` scope (classic) or Contents + Metadata + Administration (fine-grained) — via `GITHUB_TOKEN` or `--token`.
+
+## License
+
+MIT — see [LICENSE](https://github.com/jpvelasco/fundamentum/blob/main/LICENSE).
+
+fundamentum is an independent project, not affiliated with GitHub.

package/install.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// nosemgrep: all — npm install shim, not application code
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const crypto = require("crypto");
+const { spawnSync } = require("child_process");
+
+const REPO = "jpvelasco/fundamentum";
+const MAX_REDIRECTS = 5;
+const DOWNLOAD_TIMEOUT_MS = 30000;
+
+const RELEASE_HOSTS = new Set([
+  "github.com",
+  "objects.githubusercontent.com",
+  "github-releases.githubusercontent.com",
+]);
+
+const PLATFORM_MAP = {
+  linux: "linux",
+  darwin: "darwin",
+  win32: "windows",
+};
+
+const ARCH_MAP = {
+  x64: "amd64",
+  arm64: "arm64",
+};
+
+function getArchiveName(version, platform, arch) {
+  const os = PLATFORM_MAP[platform];
+  const cpu = ARCH_MAP[arch];
+  if (!os || !cpu) {
+    throw new Error(`Unsupported platform: ${platform}/${arch}`);
+  }
+  const ext = platform === "win32" ? "zip" : "tar.gz";
+  return `fundamentum_${version}_${os}_${cpu}.${ext}`;
+}
+
+function download(url, redirectCount = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirectCount > MAX_REDIRECTS) {
+      return reject(new Error(`Too many redirects (max ${MAX_REDIRECTS})`));
+    }
+
+    const req = https.get(url, { timeout: DOWNLOAD_TIMEOUT_MS }, (res) => {
+      if (
+        res.statusCode >= 300 &&
+        res.statusCode < 400 &&
+        res.headers.location
+      ) {
+        const nextUrl = new URL(res.headers.location, url);
+        if (
+          !RELEASE_HOSTS.has(nextUrl.hostname) &&
+          !nextUrl.hostname.endsWith(".githubusercontent.com")
+        ) {
+          return reject(
+            new Error(`Refusing redirect to unexpected host: ${nextUrl.hostname}`)
+          );
+        }
+        res.resume();
+        return download(nextUrl.href, redirectCount + 1).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(
+          new Error(`Download failed: HTTP ${res.statusCode} for ${url}`)
+        );
+      }
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => resolve(Buffer.concat(chunks)));
+      res.on("error", reject);
+    });
+
+    req.setTimeout(DOWNLOAD_TIMEOUT_MS, () => {
+      req.destroy(new Error(`Timed out downloading ${url}`));
+    });
+    req.on("error", reject);
+  });
+}
+
+function verifyChecksum(buffer, archiveName, pkg) {
+  const expected = pkg.binaryChecksums?.[archiveName] || null;
+  if (!expected) {
+    // A published package always has checksums embedded by the release
+    // workflow. A missing entry means asset-naming drift or tampering —
+    // fail closed rather than run an unverified binary.
+    if (pkg.version !== "0.0.0") {
+      throw new Error(
+        `No checksum found for ${archiveName}. Refusing to install an unverified binary.`
+      );
+    }
+    console.log("fundamentum: dev version, skipping checksum verification");
+    return;
+  }
+
+  const actual = crypto.createHash("sha256").update(buffer).digest("hex");
+  if (actual !== expected) {
+    throw new Error(
+      `Checksum mismatch for ${archiveName}\n` +
+        `  Expected: ${expected}\n` +
+        `  Actual:   ${actual}`
+    );
+  }
+  console.log("fundamentum: checksum verified (SHA-256)");
+}
+
+// Escape a string for use inside PowerShell single quotes.
+// PowerShell single-quoted strings only need '' to represent a literal '.
+function psEscape(s) {
+  return s.replace(/'/g, "''");
+}
+
+function spawnOrFail(cmd, args, label) {
+  const result = spawnSync(cmd, args, { stdio: "pipe" });
+  if (result.error) {
+    throw new Error(`${label}: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const stderr = result.stderr ? result.stderr.toString().trim() : "";
+    throw new Error(
+      `${label} exited with code ${result.status}${stderr ? ": " + stderr : ""}`
+    );
+  }
+}
+
+function extract(buffer, archiveName, binDir) {
+  const tmpDir = path.join(__dirname, ".tmp-install");
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  const archivePath = path.join(tmpDir, archiveName);
+  fs.writeFileSync(archivePath, buffer);
+
+  try {
+    if (archiveName.endsWith(".zip")) {
+      if (process.platform === "win32") {
+        spawnOrFail(
+          "powershell",
+          [
+            "-NoProfile",
+            "-Command",
+            `Expand-Archive -Force -Path '${psEscape(
+              archivePath
+            )}' -DestinationPath '${psEscape(tmpDir)}'`,
+          ],
+          "Expand-Archive"
+        );
+      } else {
+        spawnOrFail("unzip", ["-o", archivePath, "-d", tmpDir], "unzip");
+      }
+    } else {
+      spawnOrFail("tar", ["-xzf", archivePath, "-C", tmpDir], "tar");
+    }
+
+    // Find the binary in the extracted files
+    const binaryName = process.platform === "win32" ? "fundamentum.exe" : "fundamentum";
+    const extractedBinary = path.join(tmpDir, binaryName);
+
+    if (!fs.existsSync(extractedBinary)) {
+      throw new Error(`Binary ${binaryName} not found in archive`);
+    }
+
+    fs.mkdirSync(binDir, { recursive: true });
+    const destBinary = path.join(binDir, binaryName);
+    fs.copyFileSync(extractedBinary, destBinary);
+
+    if (process.platform !== "win32") {
+      fs.chmodSync(destBinary, 0o755);
+    }
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+async function main() {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(__dirname, "package.json"), "utf8")
+  );
+  const version = pkg.version;
+  if (version === "0.0.0") {
+    console.error("fundamentum: skipping binary download for development version");
+    return;
+  }
+
+  const archiveName = getArchiveName(version, process.platform, process.arch);
+  const url = `https://github.com/${REPO}/releases/download/v${version}/${archiveName}`;
+  const binDir = path.join(__dirname, "bin");
+
+  console.log(`fundamentum: downloading ${archiveName}...`);
+  const buffer = await download(url);
+
+  verifyChecksum(buffer, archiveName, pkg);
+
+  console.log("fundamentum: extracting binary...");
+  extract(buffer, archiveName, binDir);
+
+  console.log("fundamentum: installed successfully");
+}
+
+main().catch((err) => {
+  console.error(`fundamentum: installation failed: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "fundamentum-cli",
+  "version": "0.1.0",
+  "description": "Bootstrap and harden GitHub repos for OSS collaboration — community files, branch protection, security features, and starter workflows in one command.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jpvelasco/fundamentum.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jpvelasco/fundamentum/issues"
+  },
+  "homepage": "https://github.com/jpvelasco/fundamentum#readme",
+  "bin": {
+    "fundamentum": "run.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "keywords": [
+    "github",
+    "github-repo",
+    "repo-hardening",
+    "repository-security",
+    "branch-protection",
+    "codeowners",
+    "code-of-conduct",
+    "contributing",
+    "community-files",
+    "open-source",
+    "oss",
+    "best-practices",
+    "security",
+    "dependabot",
+    "codeql",
+    "secret-scanning",
+    "templates",
+    "scaffolding",
+    "automation",
+    "devops",
+    "cli",
+    "github-api"
+  ],
+  "files": [
+    "README.md",
+    "install.js",
+    "run.js",
+    "bin/"
+  ],
+  "binaryChecksums": {
+    "fundamentum_0.1.0_darwin_amd64.tar.gz": "9d7be6fbfee6414005932547e1cc2cef54580739a5a265573942c80bb5fd28d9",
+    "fundamentum_0.1.0_darwin_arm64.tar.gz": "e50920a5522c9739899e30aa8f9414ac8a66bfcea4b91ef98e2c38f407d54b75",
+    "fundamentum_0.1.0_linux_amd64.tar.gz": "1772182f6c1d6a13b0e23bafb01ce89a8b9316895b778ce7a38ce2a9409fff16",
+    "fundamentum_0.1.0_linux_arm64.tar.gz": "5506f3002cdd4fad7ee641dfb023672c80d0e8934602906e9c8bb35a643da4ab",
+    "fundamentum_0.1.0_windows_amd64.zip": "ba5d12e8a0dbcae168adf7f68141910e0536c186f2921adba000a5b486f68853"
+  }
+}

package/run.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// nosemgrep: all — npm run shim, not application code
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawn, spawnSync } = require("child_process");
+
+const binaryName = process.platform === "win32" ? "fundamentum.exe" : "fundamentum";
+const binaryPath = path.join(__dirname, "bin", binaryName);
+
+function runBinary() {
+  const child = spawn(binaryPath, process.argv.slice(2), {
+    stdio: "inherit",
+  });
+
+  // Forward signals so the Go binary shuts down cleanly
+  ["SIGINT", "SIGTERM", "SIGHUP"].forEach((sig) => {
+    process.on(sig, () => child.kill(sig));
+  });
+
+  child.on("error", (err) => {
+    if (err.code === "ENOENT") {
+      console.error(
+        `fundamentum: binary not found at ${binaryPath}\n` +
+          "Try running: node " +
+          path.join(__dirname, "install.js")
+      );
+    } else {
+      console.error(`fundamentum: failed to start: ${err.message}`);
+    }
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    process.exit(signal ? 1 : code || 0);
+  });
+}
+
+// If the binary is missing, postinstall was likely blocked by npm's allow-scripts
+// security policy. Attempt a lazy download, but the package dir may be root-owned
+// (e.g. sudo npm install -g). In that case, surface a clear recovery message.
+if (!fs.existsSync(binaryPath)) {
+  const installScript = path.join(__dirname, "install.js");
+
+  // Check if we can write to the package dir before attempting the download.
+  let canWrite = false;
+  try {
+    fs.accessSync(__dirname, fs.constants.W_OK);
+    canWrite = true;
+  } catch (_) {
+    // directory is not writable by current user
+  }
+
+  if (!canWrite) {
+    console.error(
+      "fundamentum: binary not found and the package directory is not writable.\n" +
+        "Run the installer with the same permissions used for npm install:\n" +
+        "  sudo node " + installScript
+    );
+    process.exit(1);
+  }
+
+  console.error(
+    "fundamentum: binary not found — postinstall was likely blocked by npm allow-scripts."
+  );
+  console.error("fundamentum: downloading binary now...");
+  const result = spawnSync(process.execPath, [installScript], {
+    stdio: "inherit",
+  });
+  if (result.error || result.status !== 0) {
+    console.error(
+      "fundamentum: download failed. Manual recovery:\n" +
+        "  node " + installScript
+    );
+    process.exit(1);
+  }
+}
+
+runBinary();