@deployanyway/ship-it-meter 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0 — 2026-10-08
+
+- Useful structured API/CLI additions described in README.
+- TypeScript declarations, CommonJS entry, coverage gates and installed archive checks.
+- Linux Node 22/24 plus Windows/macOS Node 24 CI.
+
 ## 0.2.0 — 2026-10-08
 
 - Preflight, with a parachute: `preflight(input)` returns the same score, verdict and reasons as `shipIt`, plus actionable `actions`. CLI `--checklist` includes them in text or JSON output. It uses only supplied evidence and is not a deployment guarantee.

package/MIGRATION.md

@@ -0,0 +1,5 @@
+# 0.3.0 migration
+
+Node 22.13+ is required. Existing core APIs remain available; TypeScript declarations and CommonJS exports are new. The CLI now lives in src/cli.js behind the same executable path. Input/stdout behavior for new options is documented in README.
+
+Install 0.3.0 with npm. Seeds and exact humorous wording are version-specific. Do not treat jokes or heuristic scores as production evidence.

package/README.md

@@ -1,5 +1,7 @@
 # ship-it-meter
 
+> **Version 0.3.0:** install from npm with Node 22.13+ or Node 24. See MIGRATION.md for changes from 0.2.0.
+
 [![npm version](https://img.shields.io/npm/v/%40deployanyway%2Fship-it-meter)](https://www.npmjs.com/package/@deployanyway/ship-it-meter)
 [![CI](https://github.com/DeployAnyway/ship-it-meter/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DeployAnyway/ship-it-meter/actions/workflows/ci.yml)
 
@@ -167,3 +169,43 @@ API (import the named functions from this package):
 ```js
 preflight({ tests: 125, coverage: 82, build: true, day: "friday" });
 ```
+
+## An explicit gate for automation
+
+```js
+import { releaseGate } from "@deployanyway/ship-it-meter";
+const result = releaseGate(
+  { tests: 42, coverage: 92, build: true },
+  { minScore: 80 },
+);
+console.log(result.passed, result.blockers);
+```
+
+A gate requires positive test count, coverage evidence and a passing build. Failing tests, critical issues, lint failures and dirty changes block it even when a low score threshold is chosen. Scores remain a heuristic, not authorization to deploy. The result adds passed, blockers and minScore to the preflight checklist.
+
+```sh
+node bin/cli.js --tests 42 --coverage 92 --build pass --gate --json
+node bin/cli.js --stdin --gate --min-score 90 --json < evidence.json
+```
+
+--stdin accepts a bounded JSON evidence object (256 KiB); explicit flags override fields. --min-score requires --gate and a 0–100 threshold, default 80. Exit 0: gate passes or ordinary scoring succeeds; 1: gate blocked; 2: malformed input. Upstream pipeline status is your shell's responsibility.
+
+## Run from source
+
+```sh
+git clone --branch main https://github.com/DeployAnyway/ship-it-meter.git
+cd ship-it-meter
+npm ci
+npm run build
+node bin/cli.js --help
+```
+
+## Candidate quality standard
+
+Version 0.3 provides useful declaration types, ESM/CommonJS exports, installed-archive checks, and coverage gates (90% statements/lines/functions, 85% branches). CI covers Linux Node 22/24 and Windows/macOS Node 24. Node 22.13+ is required. No runtime dependencies, telemetry or network requests.
+
+From a source checkout: npm ci, npm run build, npm run coverage, npm run test:types, npm run verify:package. Pack verification installs a temporary local archive and checks module entries, types, executable and offline npm exec.
+
+[Contribution guide](CONTRIBUTING.md) · [Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) · [Roadmap](ROADMAP.md) · [Migration](MIGRATION.md).
+
+**Tools for developers who probably know better.** Software nobody requested, built with questionable priorities, and shipped with absolute confidence!

package/bin/cli.js

@@ -1,68 +1,2 @@
 #!/usr/bin/env node
-import { parseArgs } from "node:util";
-import { readFileSync } from "node:fs";
-import { URL } from "node:url";
-import { shipIt, preflight } from "../src/index.js";
-
-try {
-  const { values } = parseArgs({
-    options: {
-      help: { type: "boolean", short: "h" },
-      version: { type: "boolean", short: "v" },
-      json: { type: "boolean" },
-      checklist: { type: "boolean" },
-      tests: { type: "string" },
-      failing: { type: "string" },
-      coverage: { type: "string" },
-      day: { type: "string" },
-      branch: { type: "string" },
-      critical: { type: "string" },
-      lint: { type: "string" },
-      build: { type: "string" },
-      dirty: { type: "boolean" },
-    },
-  });
-  if (values.help) {
-    console.log(
-      "Usage: ship-it-meter [options]\n\nOptions:\n  --tests number    Total tests\n  --failing number  Failing tests\n  --coverage number Coverage percent\n  --build pass|fail Build result\n  --critical number Open critical issues\n  --lint number     Lint failures\n  --dirty           Uncommitted changes\n  --branch name     Branch name\n  --day weekday     Full weekday name\n  --checklist       Actionable, mildly concerned preflight\n  --json            Structured output\n  -h, --help        Help\n  -v, --version     Version\n\nMissing test, coverage, and build evidence reduces readiness.\nExit codes: 0 scored successfully; 2 invalid arguments.",
-    );
-  } else if (values.version) {
-    console.log(
-      JSON.parse(
-        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-      ).version,
-    );
-  } else {
-    const input = {};
-    for (const [flag, key] of Object.entries({
-      tests: "tests",
-      failing: "failingTests",
-      coverage: "coverage",
-      critical: "criticalIssues",
-      lint: "lintFailures",
-    })) {
-      if (values[flag] !== undefined) {
-        if (!/^\d+(?:\.\d+)?$/.test(values[flag]))
-          throw new TypeError(`${flag} must be a nonnegative decimal number.`);
-        input[key] = Number(values[flag]);
-      }
-    }
-    if (values.build !== undefined) {
-      if (!["pass", "fail"].includes(values.build))
-        throw new RangeError("--build must be pass or fail.");
-      input.build = values.build === "pass";
-    }
-    for (const key of ["day", "branch"])
-      if (values[key] !== undefined) input[key] = values[key];
-    if (values.dirty) input.uncommittedChanges = true;
-    const result = values.checklist ? preflight(input) : shipIt(input);
-    console.log(
-      values.json
-        ? JSON.stringify(result, null, 2)
-        : `${result.score}/100 — ${result.verdict}\n${result.reasons.map((reason) => `- ${reason}`).join("\n")}${result.actions ? "\n\nBefore you ship:\n" + result.actions.map((action) => `[ ] ${action}`).join("\n") : ""}`,
-    );
-  }
-} catch (error) {
-  console.error(`ship-it-meter: ${error.message}\nRun with --help for usage.`);
-  process.exitCode = 2;
-}
+import "../src/cli.js";

package/dist/index.cjs

@@ -0,0 +1,183 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  preflight: () => preflight,
+  releaseGate: () => releaseGate,
+  shipIt: () => shipIt
+});
+module.exports = __toCommonJS(index_exports);
+var days = [
+  "monday",
+  "tuesday",
+  "wednesday",
+  "thursday",
+  "friday",
+  "saturday",
+  "sunday"
+];
+var counts = ["tests", "failingTests", "criticalIssues", "lintFailures"];
+var allowed = [
+  ...counts,
+  "coverage",
+  "build",
+  "uncommittedChanges",
+  "branch",
+  "day"
+];
+function releaseGate(input = {}, options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Gate options must be an object.");
+  const minScore = options.minScore ?? 80;
+  if (typeof minScore !== "number" || !Number.isFinite(minScore) || minScore < 0 || minScore > 100)
+    throw new RangeError("minScore must be between 0 and 100.");
+  const result = preflight(input);
+  const blockers = [];
+  if (!input.tests)
+    blockers.push("Provide a positive test count. Vibes cannot pass CI.");
+  if (input.build !== true) blockers.push("A passing build is required.");
+  if (input.coverage === void 0)
+    blockers.push("Coverage evidence is required.");
+  if (input.failingTests) blockers.push("Failing tests block the gate.");
+  if (input.criticalIssues) blockers.push("Critical issues block the gate.");
+  if (input.lintFailures) blockers.push("Lint failures block the gate.");
+  if (input.uncommittedChanges)
+    blockers.push("Uncommitted changes block the gate.");
+  if (result.score < minScore)
+    blockers.push(`Score ${result.score} is below ${minScore}.`);
+  return { ...result, minScore, passed: blockers.length === 0, blockers };
+}
+function shipIt(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new TypeError("Input must be an object.");
+  for (const key of Object.keys(input))
+    if (!allowed.includes(key)) throw new TypeError(`Unknown input: ${key}.`);
+  for (const key of counts) {
+    if (input[key] !== void 0 && (!Number.isSafeInteger(input[key]) || input[key] < 0))
+      throw new RangeError(`${key} must be a nonnegative safe integer.`);
+  }
+  if (input.coverage !== void 0 && (typeof input.coverage !== "number" || !Number.isFinite(input.coverage) || input.coverage < 0 || input.coverage > 100))
+    throw new RangeError("coverage must be between 0 and 100.");
+  for (const key of ["build", "uncommittedChanges"])
+    if (input[key] !== void 0 && typeof input[key] !== "boolean")
+      throw new TypeError(`${key} must be a boolean.`);
+  for (const key of ["branch", "day"])
+    if (input[key] !== void 0 && (typeof input[key] !== "string" || !input[key].trim()))
+      throw new TypeError(`${key} must be a nonempty string.`);
+  const day = input.day?.trim().toLowerCase();
+  if (day !== void 0 && !days.includes(day))
+    throw new RangeError("day must be a full weekday name.");
+  const failing = input.failingTests ?? 0;
+  if (failing > 0 && input.tests === void 0)
+    throw new RangeError("tests is required when failingTests is positive.");
+  if (input.tests !== void 0 && failing > input.tests)
+    throw new RangeError("failingTests cannot exceed tests.");
+  let score = 100;
+  const reasons = [];
+  const deduct = (points, reason) => {
+    score -= points;
+    reasons.push(`${reason} (-${points})`);
+  };
+  if (!input.tests)
+    deduct(
+      25,
+      input.tests === 0 ? "No tests reported" : "Test count not provided"
+    );
+  else if (failing)
+    deduct(
+      Math.min(50, 20 + Math.ceil(30 * (failing / input.tests))),
+      `${failing} of ${input.tests} tests are failing`
+    );
+  else reasons.push(`${input.tests} tests reported passing`);
+  if (input.coverage === void 0) deduct(15, "Coverage not provided");
+  else {
+    const penalty = Math.ceil((100 - input.coverage) * 0.2);
+    if (penalty) deduct(penalty, `Coverage is ${input.coverage}%`);
+    else reasons.push("Coverage is 100%");
+  }
+  if (input.build === void 0) deduct(15, "Build status not provided");
+  else if (!input.build) deduct(40, "Build failed");
+  else reasons.push("Build passed");
+  if (input.criticalIssues)
+    deduct(
+      Math.min(50, 25 * input.criticalIssues),
+      `${input.criticalIssues} open critical issues`
+    );
+  if (input.lintFailures)
+    deduct(
+      Math.min(20, 5 * input.lintFailures),
+      `${input.lintFailures} lint failures`
+    );
+  if (input.uncommittedChanges) deduct(10, "Uncommitted changes reported");
+  if (input.branch !== void 0 && !["main", "master"].includes(input.branch.trim()))
+    deduct(5, `Branch is ${input.branch.trim()}`);
+  if (day === "friday")
+    deduct(3, "Friday: the weekend would like a quiet entrance");
+  score = Math.max(0, Math.min(100, score));
+  if (input.build === false || input.criticalIssues > 0) {
+    score = Math.min(score, 29);
+    reasons.push("Failed build or critical issues cap the score at 29");
+  } else if (failing > 0) {
+    score = Math.min(score, 59);
+    reasons.push("Failing tests cap the score at 59");
+  }
+  const verdict = score < 30 ? "Absolutely Not" : score < 60 ? "Questionable" : score < 80 ? "Probably Fine" : score < 95 ? "Ship It" : "Suspiciously Ready";
+  return { score, verdict, reasons };
+}
+function preflight(input = {}) {
+  const result = shipIt(input);
+  const actions = [];
+  if (input.build !== true)
+    actions.push("Get a passing build. Confidence is not a build artifact.");
+  if (!input.tests)
+    actions.push("Run tests and report the count. Vibes are not assertions.");
+  if (input.failingTests)
+    actions.push("Fix failing tests. Red is not a festive deployment theme.");
+  if (input.coverage === void 0 || input.coverage < 80)
+    actions.push(
+      "Measure coverage and review untested paths. The bugs enjoy privacy."
+    );
+  if (input.criticalIssues)
+    actions.push(
+      "Resolve critical issues. The incident channel deserves a quiet afternoon."
+    );
+  if (input.lintFailures)
+    actions.push("Fix lint failures. Let the semicolons retire in peace.");
+  if (input.uncommittedChanges)
+    actions.push(
+      "Commit or stash local changes. Your laptop is not the release archive."
+    );
+  if (input.day?.trim().toLowerCase() === "friday")
+    actions.push(
+      "Confirm rollback and on-call cover. The weekend has other plans."
+    );
+  if (!actions.length)
+    actions.push(
+      "Confirm monitoring and rollback. Even excellent evidence needs a parachute."
+    );
+  return { ...result, actions };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  preflight,
+  releaseGate,
+  shipIt
+});

package/index.d.cts

@@ -0,0 +1,43 @@
+export type Weekday =
+  | "monday"
+  | "tuesday"
+  | "wednesday"
+  | "thursday"
+  | "friday"
+  | "saturday"
+  | "sunday";
+export interface Evidence {
+  tests?: number;
+  failingTests?: number;
+  coverage?: number;
+  build?: boolean;
+  uncommittedChanges?: boolean;
+  branch?: string;
+  day?: Weekday;
+  criticalIssues?: number;
+  lintFailures?: number;
+}
+export interface Readiness {
+  score: number;
+  verdict:
+    | "Absolutely Not"
+    | "Questionable"
+    | "Probably Fine"
+    | "Ship It"
+    | "Suspiciously Ready";
+  reasons: string[];
+}
+export interface Preflight extends Readiness {
+  actions: string[];
+}
+export interface Gate extends Preflight {
+  minScore: number;
+  passed: boolean;
+  blockers: string[];
+}
+export function shipIt(input?: Evidence): Readiness;
+export function preflight(input?: Evidence): Preflight;
+export function releaseGate(
+  input?: Evidence,
+  options?: { minScore?: number },
+): Gate;

package/index.d.ts

@@ -0,0 +1,43 @@
+export type Weekday =
+  | "monday"
+  | "tuesday"
+  | "wednesday"
+  | "thursday"
+  | "friday"
+  | "saturday"
+  | "sunday";
+export interface Evidence {
+  tests?: number;
+  failingTests?: number;
+  coverage?: number;
+  build?: boolean;
+  uncommittedChanges?: boolean;
+  branch?: string;
+  day?: Weekday;
+  criticalIssues?: number;
+  lintFailures?: number;
+}
+export interface Readiness {
+  score: number;
+  verdict:
+    | "Absolutely Not"
+    | "Questionable"
+    | "Probably Fine"
+    | "Ship It"
+    | "Suspiciously Ready";
+  reasons: string[];
+}
+export interface Preflight extends Readiness {
+  actions: string[];
+}
+export interface Gate extends Preflight {
+  minScore: number;
+  passed: boolean;
+  blockers: string[];
+}
+export function shipIt(input?: Evidence): Readiness;
+export function preflight(input?: Evidence): Preflight;
+export function releaseGate(
+  input?: Evidence,
+  options?: { minScore?: number },
+): Gate;

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@deployanyway/ship-it-meter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Explainable deployment readiness scoring for tests, coverage, and builds. Turns questionable confidence into a number.",
   "type": "module",
-  "exports": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./src/index.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
   "bin": {
     "ship-it-meter": "./bin/cli.js"
   },
@@ -12,16 +23,26 @@
     "bin",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "dist",
+    "index.d.ts",
+    "index.d.cts",
+    "MIGRATION.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13"
   },
   "scripts": {
-    "test": "node --test",
+    "test": "node --test test/*.test.js",
     "lint": "eslint .",
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "build": "node scripts/build.mjs",
+    "pretest": "npm run build",
+    "prepack": "npm run build",
+    "coverage": "c8 --all --include=src/**/*.js --reporter=text --reporter=json-summary --reporter=lcov --check-coverage --lines=90 --statements=90 --functions=90 --branches=85 node --test test/*.test.js",
+    "test:types": "tsc -p tsconfig.json",
+    "verify:package": "node scripts/verify-package.mjs"
   },
   "repository": {
     "type": "git",
@@ -35,8 +56,12 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/node": "^26.6.4",
+    "c8": "^12.0.0",
+    "esbuild": "^0.28.2",
     "eslint": "^10.12.0",
-    "prettier": "^3.6.2"
+    "prettier": "^3.6.2",
+    "typescript": "^7.0.2"
   },
   "keywords": [
     "nodejs",
@@ -47,6 +72,12 @@
     "readiness",
     "test-coverage",
     "build",
-    "scoring"
-  ]
+    "scoring",
+    "typescript",
+    "humor",
+    "deployanyway"
+  ],
+  "main": "./dist/index.cjs",
+  "types": "./index.d.ts",
+  "homepage": "https://deployanyway.github.io/"
 }

package/src/cli.js

@@ -0,0 +1,89 @@
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { URL } from "node:url";
+import { shipIt, preflight, releaseGate } from "./index.js";
+
+import { readStdin } from "./input.js";
+
+try {
+  const { values } = parseArgs({
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      json: { type: "boolean" },
+      stdin: { type: "boolean" },
+      gate: { type: "boolean" },
+      "min-score": { type: "string" },
+      checklist: { type: "boolean" },
+      tests: { type: "string" },
+      failing: { type: "string" },
+      coverage: { type: "string" },
+      day: { type: "string" },
+      branch: { type: "string" },
+      critical: { type: "string" },
+      lint: { type: "string" },
+      build: { type: "string" },
+      dirty: { type: "boolean" },
+    },
+  });
+  if (values.help) {
+    console.log(
+      "Usage: ship-it-meter [options]\n\nOptions:\n  --tests number    Total tests\n  --failing number  Failing tests\n  --coverage number Coverage percent\n  --build pass|fail Build result\n  --critical number Open critical issues\n  --lint number     Lint failures\n  --dirty           Uncommitted changes\n  --branch name     Branch name\n  --day weekday     Full weekday name\n  --checklist       Actionable, mildly concerned preflight\n  --json            Structured output\n  -h, --help        Help\n  -v, --version     Version\n\n--stdin reads a JSON evidence object (256 KiB); explicit flags override it. --gate requires passing evidence; --min-score 80 selects its threshold. A blocked gate exits 1. Missing test, coverage, and build evidence reduces readiness.\nExit codes: 0 scored successfully; 2 invalid arguments.",
+    );
+  } else if (values.version) {
+    console.log(
+      JSON.parse(
+        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+      ).version,
+    );
+  } else {
+    const input = values.stdin ? JSON.parse(await readStdin()) : {};
+    if (!input || typeof input !== "object" || Array.isArray(input))
+      throw new TypeError("stdin must contain an evidence object.");
+    if (
+      values["min-score"] !== undefined &&
+      (!values.gate || !/^\d+(?:\.\d+)?$/.test(values["min-score"]))
+    )
+      throw new TypeError("--min-score requires --gate and a decimal number.");
+    for (const [flag, key] of Object.entries({
+      tests: "tests",
+      failing: "failingTests",
+      coverage: "coverage",
+      critical: "criticalIssues",
+      lint: "lintFailures",
+    })) {
+      if (values[flag] !== undefined) {
+        if (!/^\d+(?:\.\d+)?$/.test(values[flag]))
+          throw new TypeError(`${flag} must be a nonnegative decimal number.`);
+        input[key] = Number(values[flag]);
+      }
+    }
+    if (values.build !== undefined) {
+      if (!["pass", "fail"].includes(values.build))
+        throw new RangeError("--build must be pass or fail.");
+      input.build = values.build === "pass";
+    }
+    for (const key of ["day", "branch"])
+      if (values[key] !== undefined) input[key] = values[key];
+    if (values.dirty) input.uncommittedChanges = true;
+    const result = values.gate
+      ? releaseGate(input, {
+          minScore:
+            values["min-score"] === undefined
+              ? undefined
+              : Number(values["min-score"]),
+        })
+      : values.checklist
+        ? preflight(input)
+        : shipIt(input);
+    if (values.gate && !result.passed) process.exitCode = 1;
+    console.log(
+      values.json
+        ? JSON.stringify(result, null, 2)
+        : `${result.score}/100 — ${result.verdict}${values.gate ? (result.passed ? " — gate passed" : " — gate blocked") : ""}\n${result.reasons.map((reason) => `- ${reason}`).join("\n")}${result.actions ? "\n\nBefore you ship:\n" + result.actions.map((action) => `[ ] ${action}`).join("\n") : ""}`,
+    );
+  }
+} catch (error) {
+  console.error(`ship-it-meter: ${error.message}\nRun with --help for usage.`);
+  process.exitCode = 2;
+}

package/src/index.js

@@ -17,6 +17,35 @@ const allowed = [
   "day",
 ];
 
+/** Explicit automation gate; a score alone is never a deployment approval. */
+export function releaseGate(input = {}, options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Gate options must be an object.");
+  const minScore = options.minScore ?? 80;
+  if (
+    typeof minScore !== "number" ||
+    !Number.isFinite(minScore) ||
+    minScore < 0 ||
+    minScore > 100
+  )
+    throw new RangeError("minScore must be between 0 and 100.");
+  const result = preflight(input);
+  const blockers = [];
+  if (!input.tests)
+    blockers.push("Provide a positive test count. Vibes cannot pass CI.");
+  if (input.build !== true) blockers.push("A passing build is required.");
+  if (input.coverage === undefined)
+    blockers.push("Coverage evidence is required.");
+  if (input.failingTests) blockers.push("Failing tests block the gate.");
+  if (input.criticalIssues) blockers.push("Critical issues block the gate.");
+  if (input.lintFailures) blockers.push("Lint failures block the gate.");
+  if (input.uncommittedChanges)
+    blockers.push("Uncommitted changes block the gate.");
+  if (result.score < minScore)
+    blockers.push(`Score ${result.score} is below ${minScore}.`);
+  return { ...result, minScore, passed: blockers.length === 0, blockers };
+}
+
 /**
  * Calculate a stateless readiness score. Missing evidence reduces the score.
  * @param {{tests?: number, failingTests?: number, coverage?: number, build?: boolean, uncommittedChanges?: boolean, branch?: string, day?: string, criticalIssues?: number, lintFailures?: number}} [input]

package/src/input.js

@@ -0,0 +1,15 @@
+/** Read bounded UTF-8 stdin without swallowing upstream failures. */
+export async function readStdin(stream = process.stdin) {
+  if (stream.isTTY) throw new TypeError("Pipe or redirect input.");
+  let size = 0;
+  const chunks = [];
+  for await (const chunk of stream) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    size += buffer.length;
+    if (size > 262144) throw new RangeError("stdin exceeds 256 KiB.");
+    chunks.push(buffer);
+  }
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+  if (!text) throw new TypeError("Provide nonempty input.");
+  return text;
+}