govgate 0.3.3 → 0.4.0

package/README.md

@@ -40,6 +40,15 @@ standard reporter.
 Completes a run left open by `--no-complete` and evaluates the gate over **all** results
 in the run (including those posted by other jobs).
 
+### `govgate sync-env`
+
+Upserts the environments declared in `govgate/config.json` to the tool. Idempotent by
+slug: an existing `dev` is updated in place, never duplicated. Takes `--url`,
+`--api-key`, `--config` (same resolution as `report`). `report` also runs this sync
+automatically before creating a run when the block is present, so a brand-new stage
+can never fail on an unknown environment — the explicit command exists for
+onboarding-time provisioning and for verifying the catalog without reporting.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -67,6 +76,15 @@ Resolution per test (results are unioned):
 {
   "suite": "checkout-regression",
   "defaultEnvironment": "dev",
+  // Code-first environment catalog (v0.4.0+): synced to the tool by slug
+  // (existing slugs update in place — never duplicated). Slugs are scoped per
+  // application, so the plain dev/uat/prod trio is safe for every service; add
+  // more (test, pre-prod, demo, …) as needed, up to 20.
+  "environments": [
+    { "slug": "dev",  "name": "DEV",  "baseUrl": "https://dev.example.com" },
+    { "slug": "uat",  "name": "UAT" },
+    { "slug": "prod", "name": "PROD", "baseUrl": "https://www.example.com", "notes": "Live." }
+  ],
   "mappings": {
     "4":  ["checkout.spec.ts::pays with saved card"],
     "7":  ["auth/*.spec.ts::*expired session*", "Login flow > redirects*"],

package/dist/index.js

@@ -46,6 +46,11 @@ var ApiClient = class {
     }
     return JSON.parse(text2);
   }
+  // Idempotent by (application, slug): existing environments are updated in
+  // place, never duplicated. The API key scopes everything to one application.
+  putEnvironments(environments) {
+    return this.request("PUT", "/api/v1/environments", { environments });
+  }
   createRun(input) {
     return this.request("POST", "/api/v1/runs", { ...input, source: "ci" });
   }
@@ -217,6 +222,9 @@ function loadFileConfig(path) {
       throw new ConfigError(`${path}: "defaultEnvironment" must be a string`);
     out.defaultEnvironment = cfg.defaultEnvironment;
   }
+  if (cfg.environments !== void 0) {
+    out.environments = parseEnvironments(path, cfg.environments);
+  }
   if (cfg.mappings !== void 0) {
     if (typeof cfg.mappings !== "object" || cfg.mappings === null)
       throw new ConfigError(`${path}: "mappings" must be an object`);
@@ -232,6 +240,38 @@ function loadFileConfig(path) {
   }
   return out;
 }
+var MAX_ENVIRONMENTS = 20;
+var SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+function parseEnvironments(path, raw) {
+  if (!Array.isArray(raw)) throw new ConfigError(`${path}: "environments" must be an array`);
+  if (raw.length > MAX_ENVIRONMENTS)
+    throw new ConfigError(`${path}: "environments" supports at most ${MAX_ENVIRONMENTS} entries`);
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const [i, entry] of raw.entries()) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+      throw new ConfigError(`${path}: environments[${i}] must be an object`);
+    const e = entry;
+    if (typeof e.slug !== "string" || !SLUG_RE.test(e.slug))
+      throw new ConfigError(
+        `${path}: environments[${i}].slug must be a lowercase slug (a-z, 0-9, hyphens)`
+      );
+    if (seen.has(e.slug))
+      throw new ConfigError(`${path}: duplicate environment slug "${e.slug}"`);
+    seen.add(e.slug);
+    if (typeof e.name !== "string" || e.name.trim() === "")
+      throw new ConfigError(`${path}: environments[${i}].name must be a non-empty string`);
+    if (e.baseUrl !== void 0 && typeof e.baseUrl !== "string")
+      throw new ConfigError(`${path}: environments[${i}].baseUrl must be a string`);
+    if (e.notes !== void 0 && typeof e.notes !== "string")
+      throw new ConfigError(`${path}: environments[${i}].notes must be a string`);
+    const decl = { slug: e.slug, name: e.name };
+    if (e.baseUrl !== void 0) decl.baseUrl = e.baseUrl;
+    if (e.notes !== void 0) decl.notes = e.notes;
+    out.push(decl);
+  }
+  return out;
+}
 function loadFileMappings(flags, cwd = process.cwd()) {
   const configPath = findConfigFile(cwd, flags.config);
   const file = configPath ? loadFileConfig(configPath) : {};
@@ -276,6 +316,7 @@ function resolveConfig(flags, cwd = process.cwd()) {
     apiKey,
     suite,
     environment,
+    environments: file.environments,
     mappings: file.mappings ?? {},
     configPath
   };
@@ -596,6 +637,18 @@ program.command("report").description("Parse test result files (JUnit XML), map
     const ci = detectCiContext();
     let runId = opts.runId ?? "";
     if (!runId) {
+      if (config.environments?.length) {
+        try {
+          const sync = await api.putEnvironments(config.environments);
+          if (sync.created > 0) {
+            console.log(`Created ${sync.created} declared environment(s).`);
+          }
+        } catch (e) {
+          console.error(
+            `Warning: environment sync failed (${e instanceof Error ? e.message : String(e)}) \u2014 continuing.`
+          );
+        }
+      }
       const run = await api.createRun({
         suiteSlug: config.suite,
         environmentSlug: config.environment,
@@ -638,6 +691,30 @@ function tryResolveConfig(flags) {
     return void 0;
   }
 }
+program.command("sync-env").description("Upsert the environments declared in govgate/config.json (idempotent by slug)").option("--url <url>", "tool URL (or GOVGATE_URL)").option("--api-key <key>", "API key (prefer GOVGATE_API_KEY)").option("--config <path>", "path to govgate/config.json (default: searched upward)").action(async (opts) => {
+  try {
+    const config = resolveConfig({
+      url: opts.url,
+      apiKey: opts.apiKey,
+      suite: "unused",
+      // environments sync does not involve a suite
+      config: opts.config
+    });
+    if (!config.environments?.length) {
+      throw new ConfigError(
+        `No "environments" declared in ${config.configPath ?? "govgate/config.json"}. Add e.g. { "environments": [{ "slug": "dev", "name": "DEV" }] } to that file.`
+      );
+    }
+    const api = new ApiClient(config.url, config.apiKey);
+    const res = await api.putEnvironments(config.environments);
+    console.log(`Environments synced: ${res.created} created, ${res.updated} updated.`);
+    for (const e of res.environments) {
+      console.log(`  ${e.slug}  ${e.name}${e.baseUrl ? `  ${e.baseUrl}` : ""}`);
+    }
+  } catch (e) {
+    handleError(e);
+  }
+});
 program.command("complete").description("Complete a run and evaluate the gate (final job of a multi-job pipeline)").requiredOption("--run-id <uuid>", "run to complete").option("--url <url>", "tool URL (or GOVGATE_URL)").option("--api-key <key>", "API key (prefer GOVGATE_API_KEY)").option("--config <path>", "path to govgate/config.json").option("--suite <slug>", "suite slug (only used for config resolution)").option("--fail-on <list>", "statuses that fail the gate: fail | fail,blocked", "fail").option("--min-executed <pct>", "minimum executed percentage required by the gate").action(async (opts) => {
   try {
     const config = resolveConfig({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "govgate",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Governance gate for releases: report CI test results (JUnit XML) to your testing tool and gate promotion on the outcome.",
   "license": "MIT",
   "author": "HatStack",