govgate 0.3.2 → 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" });
   }
@@ -114,16 +119,27 @@ function emitRunIdVariable(runId, ctx, env = process.env) {
 }
 
 // src/config.ts
-import { readFileSync, existsSync } from "fs";
+import { readFileSync, existsSync, readdirSync } from "fs";
 import { dirname, join, resolve } from "path";
 var ConfigError = class extends Error {
 };
-function findConfigFile(startDir, explicitPath) {
-  if (explicitPath) {
-    const p = resolve(startDir, explicitPath);
-    if (!existsSync(p)) throw new ConfigError(`Config file not found: ${p}`);
-    return p;
-  }
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".next",
+  ".vs",
+  ".vscode",
+  ".idea",
+  "dist",
+  "build",
+  "bin",
+  "obj",
+  "coverage",
+  ".turbo",
+  ".cache"
+]);
+var DOWNWARD_MAX_DEPTH = 6;
+function findConfigUpward(startDir) {
   let dir = resolve(startDir);
   for (; ; ) {
     const candidate = join(dir, "govgate", "config.json");
@@ -133,6 +149,58 @@ function findConfigFile(startDir, explicitPath) {
     dir = parent;
   }
 }
+function findConfigDownward(startDir) {
+  const root = resolve(startDir);
+  const found = [];
+  const queue = [{ dir: root, depth: 0 }];
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    const direct = join(dir, "govgate", "config.json");
+    if (existsSync(direct)) found.push(direct);
+    if (depth >= DOWNWARD_MAX_DEPTH) continue;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === "govgate") continue;
+      if (SKIP_DIRS.has(entry.name)) continue;
+      queue.push({ dir: join(dir, entry.name), depth: depth + 1 });
+    }
+  }
+  return [...new Set(found)].sort();
+}
+function findConfigFile(startDir, explicitPath) {
+  if (explicitPath) {
+    const p = resolve(startDir, explicitPath);
+    if (!existsSync(p)) throw new ConfigError(`Config file not found: ${p}`);
+    return p;
+  }
+  const upward = findConfigUpward(startDir);
+  if (upward) return upward;
+  const downward = findConfigDownward(startDir);
+  if (downward.length === 1) {
+    console.error(
+      `govgate: no govgate/config.json at or above ${resolve(startDir)}; using discovered ${downward[0]}`
+    );
+    return downward[0];
+  }
+  if (downward.length > 1) {
+    throw new ConfigError(
+      `Ambiguous config: found ${downward.length} govgate/config.json files under ${resolve(
+        startDir
+      )} and none at or above it:
+${downward.map((p) => `  - ${p}`).join(
+        "\n"
+      )}
+Pick one with --config <path>, pass --suite <slug>, or run govgate from the intended directory.`
+    );
+  }
+  return void 0;
+}
 function loadFileConfig(path) {
   let data;
   try {
@@ -154,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`);
@@ -169,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) : {};
@@ -197,8 +300,15 @@ function resolveConfig(flags, cwd = process.cwd()) {
     );
   }
   if (!suite) {
+    if (!configPath) {
+      throw new ConfigError(
+        `No govgate/config.json found (searched upward from ${resolve(
+          cwd
+        )}, then downward). Run govgate from your repo root or the artifact/drop folder that contains govgate/, pass --config <path>, or pass --suite <slug>.`
+      );
+    }
     throw new ConfigError(
-      'Suite missing. Pass --suite <slug> or add { "suite": "<slug>" } to govgate/config.json in the repo root.'
+      `Suite missing in ${configPath}. Add { "suite": "<slug>" } to that file or pass --suite <slug>.`
     );
   }
   return {
@@ -206,6 +316,7 @@ function resolveConfig(flags, cwd = process.cwd()) {
     apiKey,
     suite,
     environment,
+    environments: file.environments,
     mappings: file.mappings ?? {},
     configPath
   };
@@ -526,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,
@@ -568,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.2",
+  "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",