@intentius/gitlab-warden 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# gitlab-warden
+
+Declarative governance for GitLab **groups & projects** — the whole surface, in one lightweight tool you run in CI.
+
+The third [warden](https://github.com/INTENTIUS/github-warden), built on the shared
+provider-agnostic reconcile primitive in
+[`@intentius/chant/reconcile`](https://github.com/INTENTIUS/chant) — the same core
+behind [github-warden](https://github.com/INTENTIUS/github-warden) and
+[forgejo-warden](https://github.com/INTENTIUS/forgejo-warden). gitlab-warden
+supplies the GitLab layer: a REST + GraphQL client (configurable host for
+self-managed + GitLab.com), config + live-state types, a GitLab `diff()`, and the
+reconcile cycles.
+
+> 🚧 **Preview published; engine in progress.** `@intentius/gitlab-warden@0.1.0` is a
+> placeholder that establishes the package + release pipeline. The reconcile engine
+> is being built per the [roadmap epic](https://github.com/INTENTIUS/gitlab-warden/issues/21).
+
+## What it is
+
+You declare desired state in YAML (selective-by-omission — an absent field is never
+touched); warden diffs it against the live GitLab API and, in `apply` mode,
+converges it — guarded so a typo can't mass-delete.
+
+It's a **single binary + a YAML file in CI**: no state file, no HCL, no provider
+toolchain to stand up. That's the whole point — governance-as-code without the
+weight, covering the **full** GitLab governance surface in one place:
+
+- **Stateless** — diff against live, reconcile. Nothing to drift, import, or lock.
+- **Continuous drift correction** — a reconcile loop, not a one-shot apply.
+- **Selective-by-omission + ownership-gated deletes** — manage a slice of a large instance without claiming the rest.
+- **Guardrails + dry-run default** — removal cap, lockout protection.
+- **Tier-graceful** — Premium/Ultimate-gated endpoints that 403 are reported and skipped, never fatal.
+
+### Flagship: push-rule drift
+
+GitLab push rules aren't version-controlled and their inheritance is **broken** —
+copied at project creation, never propagated; change a group rule and existing
+projects don't get it (each fixed by hand). A reconcile loop that re-asserts
+declared push rules across a whole group tree fixes that, continuously. It's the
+sharpest single example of the model, but warden goes after the *entire* surface.
+
+## Coverage (the full surface)
+
+| Scope | Cycles |
+|-------|--------|
+| **Group** | settings · members · subgroup provisioning · variables · webhooks · push rules · access tokens · protected environments · integrations · MR approval settings · compliance frameworks · security policies · member roles |
+| **Project** | settings · members · protected branches · protected tags · protected environments · push rules · MR approvals · variables · webhooks · integrations · deploy keys/tokens · access tokens · advanced protections (job-token scope, registry/package protection) · compliance assignment · security policy attachment |
+| **Instance** (self-managed) | application settings · instance CI/CD variables · system hooks · custom member roles |
+
+REST for most of it; **GraphQL** for the few surfaces that require it (compliance
+frameworks, security-policy attachment, custom roles).
+
+## The one genuinely hard part
+
+GitLab is a *tree* (nested groups, inherited membership), not a flat org. Membership
+must diff against **direct** members (`/members`) while *reading* effective members
+(`/members/all`), and must **never** treat an inherited member as deletable drift
+(the DELETE fails — the grant lives at an ancestor). This is the credibility gate;
+it gets a dedicated design issue (#3) that the members cycle implements against.
+Everything else is a straightforward cycle on the shared harness.
+
+## How it relates to the sibling wardens
+
+| | github-warden | forgejo-warden | gitlab-warden |
+|---|---|---|---|
+| Hierarchy | flat org → repo | flat org → repo | **nested groups → projects** |
+| Membership | direct | team-driven | **direct + inherited** |
+| Auth | GitHub App | token, self-hosted | token, self-managed + SaaS |
+| API | REST | REST | **REST + GraphQL** |
+| Reconcile core | `@intentius/chant/reconcile` | (same) | (same) |

package/bin/gitlab-warden.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * gitlab-warden bin launcher.
+ *
+ * Committed so it exists at npm pack-validation time (before `prepublishOnly`/
+ * `build` runs). It loads the built dist/cli.js and calls the exported `run()`.
+ */
+
+import(new URL("../dist/cli.js", import.meta.url).href)
+  .then((mod) => mod.run(process.argv.slice(2)))
+  .catch((err) => {
+    process.stderr.write(`gitlab-warden: fatal: ${err?.message ?? err}\n`);
+    process.exit(3);
+  });

package/dist/cli.js

@@ -0,0 +1,31 @@
+import{createRequire as __cr}from'module';const require=__cr(import.meta.url);
+
+// src/cli.ts
+var VERSION = "0.1.0";
+var USAGE = `gitlab-warden ${VERSION} \u2014 declarative governance for GitLab groups & projects
+
+  \u26A0\uFE0F  Early preview. The reconcile engine is under active development.
+      Roadmap: https://github.com/INTENTIUS/gitlab-warden/issues/21
+
+Planned usage:
+  gitlab-warden reconcile --config <path> [--mode dry-run|apply] [--cycles ...]
+
+Flags:
+  -h, --help       Show this help
+  -v, --version    Print the version
+
+Today this command prints help only; functional reconcile arrives with the
+cycles on the roadmap.
+`;
+async function run(argv = []) {
+  const arg = argv[0];
+  if (arg === "-v" || arg === "--version") {
+    process.stdout.write(`${VERSION}
+`);
+    return;
+  }
+  process.stdout.write(USAGE);
+}
+export {
+  run
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@intentius/gitlab-warden",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Declarative governance for GitLab groups & projects — stateless, drift-correcting reconcile in CI (no Terraform state, no Ultimate)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/INTENTIUS/gitlab-warden.git"
+  },
+  "homepage": "https://github.com/INTENTIUS/gitlab-warden#readme",
+  "bugs": {
+    "url": "https://github.com/INTENTIUS/gitlab-warden/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "gitlab-warden": "bin/gitlab-warden.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "tsc": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --banner:js=\"import{createRequire as __cr}from'module';const require=__cr(import.meta.url);\" --outfile=dist/cli.js && chmod +x dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.28.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}