govgate 0.3.3 → 0.5.0

package/README.md

@@ -23,7 +23,8 @@ standard reporter.
 | `--api-key <key>` | `GOVGATE_API_KEY` | API key (env var strongly preferred) |
 | `--config <path>` | `govgate/config.json` searched upward | Config file |
 | `--suite <slug>` | config `suite` | Target suite |
-| `--env <slug>` | config `defaultEnvironment` | Environment for the run |
+| `--env <slug>` | inferred, else config `defaultEnvironment` | Environment for the run (overrides inference) |
+| `--base-url <url>` | `API_BASEURL` | Live app base URL; matched against the declared environments' `baseUrl`s to infer the environment |
 | `--name <name>` | derived from CI context | Run name |
 | `--build-version <v>` | short commit SHA from CI | Build version |
 | `--external-url <url>` | CI build URL | "Build ↗" link on the run page |
@@ -40,6 +41,32 @@ 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.
+
+## Environment inference (v0.5.0+)
+
+When `--env` is absent, `report` resolves the environment **from the deployment
+under test**: the base URL (from `--base-url` or the `API_BASEURL` env var — the
+same variable your smoke tests already use) is matched against the declared
+environments' `baseUrl`s, and the matching slug wins. Falls back to
+`defaultEnvironment` when nothing matches. Matching ignores scheme, casing, and
+trailing slashes.
+
+This makes one identical report step correct in every stage — no per-stage
+`--env` variable to configure or mis-copy. The chosen slug is always printed to
+the CI log.
+
+```
+npx govgate report "test-results/*.xml" --fail-on fail   # env inferred from API_BASEURL
+```
+
 ## Exit codes
 
 | Code | Meaning |
@@ -67,6 +94,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,60 @@ 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 normalizeBaseUrl(raw) {
+  const trimmed = raw.trim();
+  if (trimmed === "") return void 0;
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+  let url;
+  try {
+    url = new URL(withScheme);
+  } catch {
+    return void 0;
+  }
+  const path = url.pathname.replace(/\/+$/, "");
+  return `${url.host}${path}`.toLowerCase();
+}
+function inferEnvironment(environments, baseUrl) {
+  if (!baseUrl || !environments?.length) return void 0;
+  const target = normalizeBaseUrl(baseUrl);
+  if (!target) return void 0;
+  for (const env of environments) {
+    if (env.baseUrl && normalizeBaseUrl(env.baseUrl) === target) return env.slug;
+  }
+  return void 0;
+}
 function loadFileMappings(flags, cwd = process.cwd()) {
   const configPath = findConfigFile(cwd, flags.config);
   const file = configPath ? loadFileConfig(configPath) : {};
@@ -248,7 +310,22 @@ function resolveConfig(flags, cwd = process.cwd()) {
   const url = flags.url ?? process.env.GOVGATE_URL;
   const apiKey = flags.apiKey ?? process.env.GOVGATE_API_KEY;
   const suite = flags.suite ?? file.suite;
-  const environment = flags.env ?? file.defaultEnvironment;
+  let environment = flags.env;
+  if (!environment) {
+    const liveBaseUrl = flags.baseUrl ?? process.env.API_BASEURL;
+    const inferred = inferEnvironment(file.environments, liveBaseUrl);
+    if (inferred) {
+      console.error(`govgate: environment '${inferred}' inferred from base URL ${liveBaseUrl}`);
+      environment = inferred;
+    } else {
+      if (liveBaseUrl && file.environments?.some((e) => e.baseUrl)) {
+        console.error(
+          `govgate: base URL ${liveBaseUrl} matches no declared environment baseUrl` + (file.defaultEnvironment ? `; falling back to defaultEnvironment '${file.defaultEnvironment}'` : " and no defaultEnvironment is set")
+        );
+      }
+      environment = file.defaultEnvironment;
+    }
+  }
   if (!url) {
     throw new ConfigError(
       "Tool URL missing. Set GOVGATE_URL or pass --url https://<your-deployment>"
@@ -276,6 +353,7 @@ function resolveConfig(flags, cwd = process.cwd()) {
     apiKey,
     suite,
     environment,
+    environments: file.environments,
     mappings: file.mappings ?? {},
     configPath
   };
@@ -561,14 +639,18 @@ async function completeAndGate(api, url, runId, gate) {
   if (!verdict.passed) process.exit(EXIT_GATE_FAILED);
 }
 var program = new Command().name("govgate").description("Report CI test results to your testing tool and gate releases on the outcome.");
-program.command("report").description("Parse test result files (JUnit XML), map tests to cases, and report a run").argument("<files...>", "result files or globs, e.g. test-results/*.xml").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)").option("--suite <slug>", "suite slug (overrides config)").option("--env <slug>", "environment slug (overrides config)").option("--name <name>", "run name (default: derived from CI context)").option("--build-version <v>", "build version (default: short commit SHA from CI)").option("--external-url <url>", "link to the build/PR (default: from CI context)").option("--format <format>", "input format", "junit").option("--run-id <uuid>", "append results to an existing run instead of creating one").option("--no-complete", "leave the run in progress (multi-job pipelines); skips the gate").option("--fail-on <list>", "statuses that fail the gate: fail | fail,blocked", "fail").option("--min-executed <pct>", "minimum executed percentage required by the gate").option("--actor <label>", "tested-by label on results", "govgate").option("--dry-run", "parse and map only; post nothing").action(async (files, opts) => {
+program.command("report").description("Parse test result files (JUnit XML), map tests to cases, and report a run").argument("<files...>", "result files or globs, e.g. test-results/*.xml").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)").option("--suite <slug>", "suite slug (overrides config)").option("--env <slug>", "environment slug (overrides config and inference)").option(
+  "--base-url <url>",
+  "base URL of the app under test; matched against the declared environments' baseUrls to infer the environment (default: API_BASEURL)"
+).option("--name <name>", "run name (default: derived from CI context)").option("--build-version <v>", "build version (default: short commit SHA from CI)").option("--external-url <url>", "link to the build/PR (default: from CI context)").option("--format <format>", "input format", "junit").option("--run-id <uuid>", "append results to an existing run instead of creating one").option("--no-complete", "leave the run in progress (multi-job pipelines); skips the gate").option("--fail-on <list>", "statuses that fail the gate: fail | fail,blocked", "fail").option("--min-executed <pct>", "minimum executed percentage required by the gate").option("--actor <label>", "tested-by label on results", "govgate").option("--dry-run", "parse and map only; post nothing").action(async (files, opts) => {
   try {
     const flags = {
       url: opts.url,
       apiKey: opts.apiKey,
       suite: opts.suite,
       env: opts.env,
-      config: opts.config
+      config: opts.config,
+      baseUrl: opts.baseUrl
     };
     const tests = await parseFiles(files, opts.format);
     const config = opts.dryRun ? tryResolveConfig(flags) : resolveConfig(flags);
@@ -596,6 +678,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 +732,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.5.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",