@deployanyway/ship-it-meter 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0
+
+Twelve named demonstration scenarios show passing evidence, Friday releases, missing evidence, failed builds, failing tests, low coverage, critical issues, lint failures, dirty worktrees, feature branches, zero tests and weekend incidents. These are examples, never evidence about your real project.
+
+```sh
+
+
+## 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.
@@ -15,3 +28,4 @@
 
 - Deterministic readiness score with explanations and technical blocker caps.
 - CLI, documented scoring rules, tests, linting, formatting, and Node 22/24 CI.
+```

package/MIGRATION.md

@@ -0,0 +1,11 @@
+# 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.
+
+## 0.3.0 to 0.4.0
+
+12 discoverable evidence scenarios and releasePlan with ordered blocker/review/release tasks and observable completion criteria; API and CLI scenarios/plans; passing/blocked gate exit codes preserved.
+
+Existing defaults and entry points remain available. The new release plan and demonstration scenarios are opt-in; the original scoring and gate rules are retained.

package/README.md

@@ -1,5 +1,30 @@
 # ship-it-meter
 
+## Evidence into an actual release plan (0.4.0)
+
+Twelve named demonstration scenarios show passing evidence, Friday releases, missing evidence, failed builds, failing tests, low coverage, critical issues, lint failures, dirty worktrees, feature branches, zero tests and weekend incidents. These are examples, never evidence about your real project.
+
+```sh
+npx @deployanyway/ship-it-meter --list-scenarios
+npx @deployanyway/ship-it-meter --scenario failed-build --plan
+npx @deployanyway/ship-it-meter --scenario ready --plan --json
+```
+
+```js
+import {
+  releasePlan,
+  releaseScenarios,
+  scenarioEvidence,
+} from "@deployanyway/ship-it-meter";
+console.log(releaseScenarios());
+const plan = releasePlan(scenarioEvidence("failing-tests"), { minScore: 80 });
+console.log(plan.passed, plan.summary, plan.tasks);
+```
+
+`releasePlan(evidence?, options?)` includes the existing gate plus prioritized tasks with stable IDs and observable verification criteria. Priorities are blocker, review and release. `scenarioEvidence(name)` and `releaseScenarios()` return independent evidence copies. CLI flags override scenario fields; stdin and scenario cannot be combined. Choose one of plan, gate or checklist. A blocked plan/gate exits 1; invalid input exits 2. Readiness remains a heuristic based on caller-supplied evidence; it does not run CI or approve deployment automatically. Coverage below 80 adds a review task, not a separate hard blocker; the configured score threshold and existing gate rules still decide the gate.
+
+> **Version 0.4.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 +192,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,417 @@
+"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,
+  releasePlan: () => releasePlan,
+  releaseScenarios: () => releaseScenarios,
+  scenarioEvidence: () => scenarioEvidence,
+  shipIt: () => shipIt
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/scenarios.js
+var scenarios = {
+  ready: {
+    description: "Passing evidence, clean worktree and main branch. Boring is a compliment.",
+    evidence: {
+      tests: 125,
+      coverage: 96,
+      build: true,
+      branch: "main",
+      day: "tuesday"
+    }
+  },
+  friday: {
+    description: "Good evidence on Friday. Confirm rollback and on-call before the victory lap.",
+    evidence: {
+      tests: 125,
+      coverage: 92,
+      build: true,
+      branch: "main",
+      day: "friday"
+    }
+  },
+  "no-evidence": {
+    description: "Confidence is present. Test, coverage and build evidence have not arrived.",
+    evidence: {}
+  },
+  "failed-build": {
+    description: "The build is red. The deploy button is not a color correction tool.",
+    evidence: {
+      tests: 125,
+      coverage: 92,
+      build: false
+    }
+  },
+  "failing-tests": {
+    description: "Some tests fail. Green deployment lights will not repair assertions.",
+    evidence: {
+      tests: 125,
+      failingTests: 3,
+      coverage: 92,
+      build: true
+    }
+  },
+  "low-coverage": {
+    description: "A passing build with many untested paths. The bugs appreciate the privacy.",
+    evidence: {
+      tests: 125,
+      coverage: 45,
+      build: true
+    }
+  },
+  "critical-issue": {
+    description: "A critical issue blocks the gate even when everything else looks cheerful.",
+    evidence: {
+      tests: 125,
+      coverage: 96,
+      build: true,
+      criticalIssues: 1
+    }
+  },
+  "lint-failures": {
+    description: "Lint failures are still failures, however decorative the semicolons feel.",
+    evidence: {
+      tests: 125,
+      coverage: 96,
+      build: true,
+      lintFailures: 2
+    }
+  },
+  "dirty-worktree": {
+    description: "The laptop contains uncommitted changes. It is not the release archive.",
+    evidence: {
+      tests: 125,
+      coverage: 96,
+      build: true,
+      uncommittedChanges: true
+    }
+  },
+  "feature-branch": {
+    description: "Healthy evidence on a feature branch. Verify the intended release source.",
+    evidence: {
+      tests: 125,
+      coverage: 96,
+      build: true,
+      branch: "feature/zoomies"
+    }
+  },
+  "zero-tests": {
+    description: "No tests ran. Zero failures is an especially small achievement here.",
+    evidence: {
+      tests: 0,
+      coverage: 0,
+      build: true
+    }
+  },
+  "weekend-incident": {
+    description: "A failed build, failing tests and a critical issue. Bring evidence, not a bigger confidence hat.",
+    evidence: {
+      tests: 125,
+      failingTests: 12,
+      coverage: 60,
+      build: false,
+      criticalIssues: 1,
+      day: "saturday"
+    }
+  }
+};
+function releaseScenarios() {
+  return Object.entries(scenarios).map(([name, value]) => ({
+    name,
+    description: value.description,
+    evidence: { ...value.evidence }
+  }));
+}
+function scenarioEvidence(name) {
+  if (typeof name !== "string" || !Object.hasOwn(scenarios, name))
+    throw new RangeError(
+      "Unknown scenario. Choose: " + Object.keys(scenarios).join(", ")
+    );
+  return { ...scenarios[name].evidence };
+}
+
+// src/index.js
+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 };
+}
+function releasePlan(input = {}, options = {}) {
+  const gate = releaseGate(input, options);
+  const tasks = [];
+  const add = (id, priority, title, verify) => tasks.push({ id, priority, title, verify });
+  if (input.build !== true)
+    add(
+      "build",
+      "blocker",
+      "Get a passing build",
+      "Run the release build for the exact commit and record its successful result."
+    );
+  if (!input.tests)
+    add(
+      "tests",
+      "blocker",
+      "Run a nonempty test suite",
+      "Record the test count and outcome for the release commit."
+    );
+  if (input.failingTests)
+    add(
+      "failing-tests",
+      "blocker",
+      "Repair failing tests",
+      "Reproduce each failure, fix its cause and rerun the suite."
+    );
+  if (input.coverage === void 0)
+    add(
+      "coverage-evidence",
+      "blocker",
+      "Measure coverage",
+      "Generate coverage for the release commit and record the percentage."
+    );
+  else if (input.coverage < 80)
+    add(
+      "coverage-review",
+      "review",
+      "Review untested paths",
+      "Inspect uncovered critical paths and add meaningful tests where needed."
+    );
+  if (input.criticalIssues)
+    add(
+      "critical-issues",
+      "blocker",
+      "Resolve critical issues",
+      "Record the resolution and verify the affected behavior."
+    );
+  if (input.lintFailures)
+    add(
+      "lint",
+      "blocker",
+      "Fix lint failures",
+      "Run the configured lint checks successfully."
+    );
+  if (input.uncommittedChanges)
+    add(
+      "worktree",
+      "blocker",
+      "Reconcile local changes",
+      "Commit or stash intentionally and verify the exact release source."
+    );
+  if (input.branch && !["main", "master"].includes(input.branch.trim()))
+    add(
+      "branch",
+      "review",
+      "Confirm release branch",
+      "Verify that this branch is the intended release source and that its CI passed."
+    );
+  if (input.day?.trim().toLowerCase() === "friday")
+    add(
+      "friday",
+      "review",
+      "Confirm weekend support",
+      "Identify monitoring ownership and a tested rollback path."
+    );
+  if (gate.score < gate.minScore)
+    add(
+      "score",
+      "blocker",
+      "Improve evidence to the configured threshold",
+      "Address score deductions, rerun the checks and reevaluate the gate."
+    );
+  add(
+    "rollback",
+    "release",
+    "Prepare the return route",
+    "Verify the rollback artifact and procedure before deployment."
+  );
+  add(
+    "monitoring",
+    "release",
+    "Watch the actual release",
+    "Check health and error metrics after deployment and name an owner."
+  );
+  const summaries = {
+    "Absolutely Not": "The evidence says stop. The confidence hat can wait.",
+    Questionable: "The release has questions. Answer them before adding confetti.",
+    "Probably Fine": "Close is a useful direction, not a deployment receipt.",
+    "Ship It": "Good evidence. Keep the parachute and watch the landing.",
+    "Suspiciously Ready": "Boring, verified readiness. Give the checks their share of the applause."
+  };
+  const rank = { blocker: 0, review: 1, release: 2 };
+  tasks.sort((a, b) => rank[a.priority] - rank[b.priority]);
+  return { ...gate, summary: summaries[gate.verdict], tasks };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  preflight,
+  releaseGate,
+  releasePlan,
+  releaseScenarios,
+  scenarioEvidence,
+  shipIt
+});

package/index.d.cts

@@ -0,0 +1,65 @@
+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;
+
+export interface ReleaseTask {
+  id: string;
+  priority: "blocker" | "review" | "release";
+  title: string;
+  verify: string;
+}
+export interface ReleasePlan extends Gate {
+  summary: string;
+  tasks: ReleaseTask[];
+}
+export interface ReleaseScenario {
+  name: string;
+  description: string;
+  evidence: Evidence;
+}
+export function releaseScenarios(): ReleaseScenario[];
+export function scenarioEvidence(name: string): Evidence;
+export function releasePlan(
+  input?: Evidence,
+  options?: { minScore?: number },
+): ReleasePlan;

package/index.d.ts

@@ -0,0 +1,65 @@
+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;
+
+export interface ReleaseTask {
+  id: string;
+  priority: "blocker" | "review" | "release";
+  title: string;
+  verify: string;
+}
+export interface ReleasePlan extends Gate {
+  summary: string;
+  tasks: ReleaseTask[];
+}
+export interface ReleaseScenario {
+  name: string;
+  description: string;
+  evidence: Evidence;
+}
+export function releaseScenarios(): ReleaseScenario[];
+export function scenarioEvidence(name: string): Evidence;
+export function releasePlan(
+  input?: Evidence,
+  options?: { minScore?: number },
+): ReleasePlan;

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@deployanyway/ship-it-meter",
-  "version": "0.2.0",
+  "version": "0.4.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,129 @@
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { URL } from "node:url";
+import {
+  shipIt,
+  preflight,
+  releaseGate,
+  releasePlan,
+  releaseScenarios,
+  scenarioEvidence,
+} 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" },
+      plan: { type: "boolean" },
+      scenario: { type: "string" },
+      "list-scenarios": { 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  --scenario name   Explore a named evidence scenario\n  --list-scenarios  List sample scenarios\n  --plan            Gate plus prioritized tasks and verification criteria\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 if (values["list-scenarios"]) {
+    console.log(
+      releaseScenarios()
+        .map((item) => item.name + " — " + item.description)
+        .join("\n"),
+    );
+  } else {
+    const input = values.stdin
+      ? JSON.parse(await readStdin())
+      : values.scenario !== undefined
+        ? scenarioEvidence(values.scenario)
+        : {};
+    if (values.stdin && values.scenario !== undefined)
+      throw new TypeError("Choose --stdin or --scenario, not both.");
+    if ([values.gate, values.plan, values.checklist].filter(Boolean).length > 1)
+      throw new TypeError("Choose one of --gate, --plan or --checklist.");
+    if (!input || typeof input !== "object" || Array.isArray(input))
+      throw new TypeError("stdin must contain an evidence object.");
+    if (
+      values["min-score"] !== undefined &&
+      (!(values.gate || values.plan) ||
+        !/^\d+(?:\.\d+)?$/.test(values["min-score"]))
+    )
+      throw new TypeError(
+        "--min-score requires --gate or --plan 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 || values.plan
+        ? (values.plan ? releasePlan : releaseGate)(input, {
+            minScore:
+              values["min-score"] === undefined
+                ? undefined
+                : Number(values["min-score"]),
+          })
+        : values.checklist
+          ? preflight(input)
+          : shipIt(input);
+    if ((values.gate || values.plan) && !result.passed) process.exitCode = 1;
+    if (values.plan && !values.json)
+      console.log(
+        result.summary +
+          "\n" +
+          result.tasks
+            .map(
+              (task) =>
+                `[${task.priority}] ${task.title}\n  Verify: ${task.verify}`,
+            )
+            .join("\n") +
+          "\n",
+      );
+    console.log(
+      values.json
+        ? JSON.stringify(result, null, 2)
+        : `${result.score}/100 — ${result.verdict}${values.gate || values.plan ? (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]
@@ -158,3 +187,113 @@ export function preflight(input = {}) {
     );
   return { ...result, actions };
 }
+
+export { releaseScenarios, scenarioEvidence } from "./scenarios.js";
+/** Explain the gate as ordered work with observable completion criteria. */
+export function releasePlan(input = {}, options = {}) {
+  const gate = releaseGate(input, options);
+  const tasks = [];
+  const add = (id, priority, title, verify) =>
+    tasks.push({ id, priority, title, verify });
+  if (input.build !== true)
+    add(
+      "build",
+      "blocker",
+      "Get a passing build",
+      "Run the release build for the exact commit and record its successful result.",
+    );
+  if (!input.tests)
+    add(
+      "tests",
+      "blocker",
+      "Run a nonempty test suite",
+      "Record the test count and outcome for the release commit.",
+    );
+  if (input.failingTests)
+    add(
+      "failing-tests",
+      "blocker",
+      "Repair failing tests",
+      "Reproduce each failure, fix its cause and rerun the suite.",
+    );
+  if (input.coverage === undefined)
+    add(
+      "coverage-evidence",
+      "blocker",
+      "Measure coverage",
+      "Generate coverage for the release commit and record the percentage.",
+    );
+  else if (input.coverage < 80)
+    add(
+      "coverage-review",
+      "review",
+      "Review untested paths",
+      "Inspect uncovered critical paths and add meaningful tests where needed.",
+    );
+  if (input.criticalIssues)
+    add(
+      "critical-issues",
+      "blocker",
+      "Resolve critical issues",
+      "Record the resolution and verify the affected behavior.",
+    );
+  if (input.lintFailures)
+    add(
+      "lint",
+      "blocker",
+      "Fix lint failures",
+      "Run the configured lint checks successfully.",
+    );
+  if (input.uncommittedChanges)
+    add(
+      "worktree",
+      "blocker",
+      "Reconcile local changes",
+      "Commit or stash intentionally and verify the exact release source.",
+    );
+  if (input.branch && !["main", "master"].includes(input.branch.trim()))
+    add(
+      "branch",
+      "review",
+      "Confirm release branch",
+      "Verify that this branch is the intended release source and that its CI passed.",
+    );
+  if (input.day?.trim().toLowerCase() === "friday")
+    add(
+      "friday",
+      "review",
+      "Confirm weekend support",
+      "Identify monitoring ownership and a tested rollback path.",
+    );
+  if (gate.score < gate.minScore)
+    add(
+      "score",
+      "blocker",
+      "Improve evidence to the configured threshold",
+      "Address score deductions, rerun the checks and reevaluate the gate.",
+    );
+  add(
+    "rollback",
+    "release",
+    "Prepare the return route",
+    "Verify the rollback artifact and procedure before deployment.",
+  );
+  add(
+    "monitoring",
+    "release",
+    "Watch the actual release",
+    "Check health and error metrics after deployment and name an owner.",
+  );
+  const summaries = {
+    "Absolutely Not": "The evidence says stop. The confidence hat can wait.",
+    Questionable:
+      "The release has questions. Answer them before adding confetti.",
+    "Probably Fine": "Close is a useful direction, not a deployment receipt.",
+    "Ship It": "Good evidence. Keep the parachute and watch the landing.",
+    "Suspiciously Ready":
+      "Boring, verified readiness. Give the checks their share of the applause.",
+  };
+  const rank = { blocker: 0, review: 1, release: 2 };
+  tasks.sort((a, b) => rank[a.priority] - rank[b.priority]);
+  return { ...gate, summary: summaries[gate.verdict], tasks };
+}

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;
+}

package/src/scenarios.js

@@ -0,0 +1,133 @@
+// Demonstration inputs, never a claim about a real release.
+const scenarios = {
+  ready: {
+    description:
+      "Passing evidence, clean worktree and main branch. Boring is a compliment.",
+    evidence: {
+      tests: 125,
+      coverage: 96,
+      build: true,
+      branch: "main",
+      day: "tuesday",
+    },
+  },
+  friday: {
+    description:
+      "Good evidence on Friday. Confirm rollback and on-call before the victory lap.",
+    evidence: {
+      tests: 125,
+      coverage: 92,
+      build: true,
+      branch: "main",
+      day: "friday",
+    },
+  },
+  "no-evidence": {
+    description:
+      "Confidence is present. Test, coverage and build evidence have not arrived.",
+    evidence: {},
+  },
+  "failed-build": {
+    description:
+      "The build is red. The deploy button is not a color correction tool.",
+    evidence: {
+      tests: 125,
+      coverage: 92,
+      build: false,
+    },
+  },
+  "failing-tests": {
+    description:
+      "Some tests fail. Green deployment lights will not repair assertions.",
+    evidence: {
+      tests: 125,
+      failingTests: 3,
+      coverage: 92,
+      build: true,
+    },
+  },
+  "low-coverage": {
+    description:
+      "A passing build with many untested paths. The bugs appreciate the privacy.",
+    evidence: {
+      tests: 125,
+      coverage: 45,
+      build: true,
+    },
+  },
+  "critical-issue": {
+    description:
+      "A critical issue blocks the gate even when everything else looks cheerful.",
+    evidence: {
+      tests: 125,
+      coverage: 96,
+      build: true,
+      criticalIssues: 1,
+    },
+  },
+  "lint-failures": {
+    description:
+      "Lint failures are still failures, however decorative the semicolons feel.",
+    evidence: {
+      tests: 125,
+      coverage: 96,
+      build: true,
+      lintFailures: 2,
+    },
+  },
+  "dirty-worktree": {
+    description:
+      "The laptop contains uncommitted changes. It is not the release archive.",
+    evidence: {
+      tests: 125,
+      coverage: 96,
+      build: true,
+      uncommittedChanges: true,
+    },
+  },
+  "feature-branch": {
+    description:
+      "Healthy evidence on a feature branch. Verify the intended release source.",
+    evidence: {
+      tests: 125,
+      coverage: 96,
+      build: true,
+      branch: "feature/zoomies",
+    },
+  },
+  "zero-tests": {
+    description:
+      "No tests ran. Zero failures is an especially small achievement here.",
+    evidence: {
+      tests: 0,
+      coverage: 0,
+      build: true,
+    },
+  },
+  "weekend-incident": {
+    description:
+      "A failed build, failing tests and a critical issue. Bring evidence, not a bigger confidence hat.",
+    evidence: {
+      tests: 125,
+      failingTests: 12,
+      coverage: 60,
+      build: false,
+      criticalIssues: 1,
+      day: "saturday",
+    },
+  },
+};
+export function releaseScenarios() {
+  return Object.entries(scenarios).map(([name, value]) => ({
+    name,
+    description: value.description,
+    evidence: { ...value.evidence },
+  }));
+}
+export function scenarioEvidence(name) {
+  if (typeof name !== "string" || !Object.hasOwn(scenarios, name))
+    throw new RangeError(
+      "Unknown scenario. Choose: " + Object.keys(scenarios).join(", "),
+    );
+  return { ...scenarios[name].evidence };
+}