@pukaradhikari/plumb-gates — the gate CLI

Versioned gate logic for Plumb. A plumbed repo runs npx @pukaradhikari/plumb-gates <gate> against a thin, repo-local config; the logic lives here and propagates to every repo on the next version bump (ADR-0001 decision c, publication in ADR-0004 — see ../GATE-STANDARD.md).

Usage

plumb-gates <gate> [--config <path>]

Config is read from --config, else plumb.config.json / .plumbrc.json / .plumbrc in the working directory. Exit code is the signal: non-zero on ERROR-severity findings, 0 otherwise.

Gates

| Gate | What it checks | Time-based? | |---|---|---| | crawl | technical crawl over a built static site: broken internal links, missing/dup/over-length title+description, missing/multiple H1, missing canonical, missing alt, orphans | no — runs on PRs | | freshness | data-currency: every configured single-source data file's lastVerified is within its review cadence | yes — also run on a daily cron |

Severity (per the Gate Standard)

• crawl — ERROR: broken links, missing title/description/h1, multiple h1, missing canonical. WARN (reported, non-blocking): orphans, duplicate/over-length metadata, missing alt.
• freshness — ERROR: OVERDUE or missing/unparseable date. WARN: DUE SOON (within graceDays of the cadence).

Config

{
  "plumbVersion": "1.0.0",
  "adapter": "web-static",
  "gates": {
    "crawl": {
      "distDir": "dist",
      "publicDir": "public",
      "titleMaxLen": 60,
      "descMaxLen": 160,
      "utilityPages": ["/", "/404/"]      // indexable pages allowed to be unlinked
    },
    "freshness": {
      "graceDays": 30,                     // DUE SOON window before the cadence
      "sources": [
        {
          "file": "src/data/example.json",
          "label": "Example volatile facts",
          "maxAgeDays": 120,               // review cadence; past it → OVERDUE
          "source": "where to re-verify from",
          "mode": "root",                  // "root" | "perEntry"
          "dateField": "lastVerified"       // optional, defaults to lastVerified
        }
      ]
    }
  }
}

mode generalizes the origin project's per-file collect() function:

• root — the date lives at the document root (json.lastVerified).
• perEntry — each top-level object entry carries its own date; keys beginning with _ are skipped; the oldest entry drives the status.

A starter config lives at ../adapters/web-static/plumb.config.example.json.

Local development (from a checkout)

The published package is the normal path (npx @pukaradhikari/plumb-gates <gate>). To run directly from a checkout instead:

node gates/bin/plumb-gates.mjs crawl --config plumb.config.json
node gates/bin/plumb-gates.mjs freshness --config plumb.config.json

No dependencies — the gates import only Node built-ins, so CI needs no install step for freshness (and only the project's own build for crawl).