@deployanyway/excuse-js 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
 
 - Meeting preparation mode: Generate 1–20 excuses with `excuseBatch(category, { count, seed })`. A batch cycles through the category without repeats until its pool is exhausted. Seeds keep the starting point repeatable. CLI `--json` returns a string or array.

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 @@
 # excuse-js
 
+> **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%2Fexcuse-js)](https://www.npmjs.com/package/@deployanyway/excuse-js)
 [![CI](https://github.com/DeployAnyway/excuse-js/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DeployAnyway/excuse-js/actions/workflows/ci.yml)
 
@@ -126,3 +128,41 @@ API (import the named functions from this package):
 ```js
 excuseBatch("deployment", { count: 3, seed: "demo" });
 ```
+
+## Jokes with a useful exit strategy
+
+```js
+import { excuseReport } from "@deployanyway/excuse-js";
+const report = excuseReport("testing", { seed: 42 });
+console.log(report.excuse);
+console.log(report.nextStep);
+```
+
+The structured report pairs the original comic excuse with a category-specific, honest next step. It does not invent evidence or recommend lying. Seeds are stateless and version-specific; numeric 42 differs from the CLI's string seed "42".
+
+```sh
+node bin/cli.js testing --report --seed demo
+node bin/cli.js deployment --report --json
+```
+
+--report cannot be combined with --count or --list. Existing string and batch JSON output stays available. No stdin is needed: this generator has no external input payload. Do not use jokes as incident reports.
+
+## Run from source
+
+```sh
+git clone --branch main https://github.com/DeployAnyway/excuse-js.git
+cd excuse-js
+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,61 +1,2 @@
 #!/usr/bin/env node
-import { parseArgs } from "node:util";
-import { readFileSync } from "node:fs";
-import { URL } from "node:url";
-import { excuse, categories, excuseBatch } from "../src/index.js";
-
-try {
-  const { values, positionals } = parseArgs({
-    allowPositionals: true,
-    options: {
-      help: { type: "boolean", short: "h" },
-      version: { type: "boolean", short: "v" },
-      seed: { type: "string" },
-      list: { type: "boolean" },
-      count: { type: "string" },
-      json: { type: "boolean" },
-    },
-  });
-  if (values.help) {
-    console.log(
-      "Usage: excuse-js [category] [--seed text] [--count 3] [--json]\n\nDefault category: deployment\n\nOptions:\n  --seed text    Repeatable selection (always a string seed)\n  --count 1..20  Prepare a batch for the meeting\n  --json         Structured string or batch\n  --list         List categories\n  -h, --help     Show help\n  -v, --version  Show version\n\nExample: excuse-js deployment --seed demo\nExit codes: 0 success; 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) {
-    if (
-      positionals.length ||
-      values.seed !== undefined ||
-      values.count !== undefined ||
-      values.json
-    )
-      throw new TypeError("--list does not accept a category or seed.");
-    console.log(categories().join("\n"));
-  } else {
-    if (positionals.length > 1)
-      throw new TypeError("Provide only one category.");
-    if (values.count !== undefined && !/^[0-9]+$/.test(values.count))
-      throw new TypeError("count must be an integer.");
-    const result =
-      values.count === undefined
-        ? excuse(positionals[0], { seed: values.seed })
-        : excuseBatch(positionals[0], {
-            seed: values.seed,
-            count: Number(values.count),
-          });
-    console.log(
-      values.json
-        ? JSON.stringify(result)
-        : Array.isArray(result)
-          ? result.map((line, i) => `${i + 1}. ${line}`).join("\n")
-          : result,
-    );
-  }
-} catch (error) {
-  console.error(`excuse-js: ${error.message}\nRun with --help for usage.`);
-  process.exitCode = 2;
-}
+import "../src/cli.js";

package/dist/index.cjs

@@ -0,0 +1,161 @@
+"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, {
+  categories: () => categories,
+  excuse: () => excuse,
+  excuseBatch: () => excuseBatch,
+  excuseReport: () => excuseReport
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/excuses.js
+var phrases = {
+  deployment: [
+    "The deployment passed rehearsal and requested a stunt double for production.",
+    "The release arrived on time. Its dependencies are still finding parking.",
+    "The deployment is waiting for the server to finish its dramatic entrance."
+  ],
+  build: [
+    "The compiler found a typo and promoted it to a company-wide announcement.",
+    "The build is assembling a committee to discuss the missing semicolon.",
+    "The artifacts are ready; the build is negotiating custody."
+  ],
+  production: [
+    "Production interpreted the happy path as an optional scenic route.",
+    "The server is performing an unscheduled demonstration of our recovery plan.",
+    "Production has requested that our assumptions submit identification."
+  ],
+  bug: [
+    "The edge case moved to the center and brought furniture.",
+    "That variable has been exploring career opportunities outside its scope.",
+    "The bug declined to reproduce until the screen-sharing session began."
+  ],
+  api: [
+    "The API sent a response, but it used the envelope for the payload.",
+    "The endpoint is observing a moment of silence for our timeout setting.",
+    "The contract was clear. The response preferred interpretive dance."
+  ],
+  database: [
+    "The database is taking a full-table stroll to consider our question.",
+    "The query asked for one row and accidentally invited the whole neighborhood.",
+    "The migration packed the columns but forgot the forwarding address."
+  ],
+  deadline: [
+    "The estimate included coding time, but the calendar added plot twists.",
+    "The deadline arrived before the requirements finished introducing themselves.",
+    "The last ten percent has applied for its own project manager."
+  ],
+  testing: [
+    "The test fixture has developed stronger opinions than the specification.",
+    "The flaky test only accepts results delivered under a full cache.",
+    "The assertion expected certainty; the asynchronous task offered suspense."
+  ],
+  network: [
+    "The packets took a detour to admire the routing table.",
+    "DNS is still deciding which address feels most like home.",
+    "The connection is buffering its explanation for the delay."
+  ],
+  "merge-conflict": [
+    "Both branches brought a solution and neither brought a seating chart.",
+    "Git discovered that two correct answers wanted the same line.",
+    "The branches agree on the goal and disagree on every comma."
+  ],
+  demo: [
+    "The demo saw an audience and switched from software to performance art.",
+    "The prototype is saving its best behavior for the recording we forgot to start.",
+    "The live demo has added a surprise question to the presentation."
+  ]
+};
+
+// src/index.js
+var nextSteps = {
+  deployment: "Check the release diff and rollback plan before delivering this line.",
+  testing: "Reproduce the failure and add a regression test. The punchline is optional.",
+  build: "Read the first build error, verify dependencies, then rebuild. The compiler does not accept applause.",
+  production: "Check health metrics and the latest release diff; confirm rollback before improving the punchline.",
+  bug: "Save a minimal reproduction and add a regression test. The bug would prefer neither.",
+  api: "Inspect the status, payload and timeout contract. The endpoint is not communicating through vibes.",
+  database: "Check connectivity and migration state before retrying. The data deserves a backup, not a speech.",
+  deadline: "Name the smallest deliverable and communicate the revised estimate. Calendars cannot compile optimism.",
+  network: "Check DNS, connectivity and timeout settings. Blame needs a packet capture.",
+  demo: "Rehearse the happy path and prepare an offline fallback. The projector can smell confidence."
+};
+function excuseReport(category = "deployment", options = {}) {
+  const text = excuse(category, options);
+  const key = category.trim().toLowerCase();
+  return {
+    category: key,
+    excuse: text,
+    nextStep: nextSteps[key] ?? "Read the evidence, name an owner, and document the next small fix."
+  };
+}
+function categories() {
+  return Object.keys(phrases);
+}
+function excuse(category = "deployment", options = {}) {
+  if (typeof category !== "string" || !category.trim())
+    throw new TypeError("Category must be a nonempty string.");
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Options must be an object.");
+  const key = category.trim().toLowerCase();
+  if (!Object.hasOwn(phrases, key))
+    throw new RangeError(
+      `Unknown category: ${category}. Choose: ${categories().join(", ")}.`
+    );
+  const { seed } = options;
+  let index;
+  if (seed === void 0) {
+    index = Math.floor(Math.random() * phrases[key].length);
+  } else {
+    if (typeof seed !== "string" && !(typeof seed === "number" && Number.isFinite(seed)))
+      throw new TypeError("Seed must be a string or finite number.");
+    const input = `${key}:${typeof seed}:${seed}`;
+    let hash = 2166136261;
+    for (let i = 0; i < input.length; i++) {
+      hash ^= input.charCodeAt(i);
+      hash = Math.imul(hash, 16777619) >>> 0;
+    }
+    index = hash % phrases[key].length;
+  }
+  return phrases[key][index];
+}
+function excuseBatch(category = "deployment", options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Options must be an object.");
+  const count = options.count ?? 3;
+  if (!Number.isSafeInteger(count) || count < 1 || count > 20)
+    throw new RangeError("count must be an integer between 1 and 20.");
+  const first = excuse(category, { seed: options.seed });
+  const pool = phrases[category.trim().toLowerCase()];
+  const start = pool.indexOf(first);
+  return Array.from(
+    { length: count },
+    (_, i) => pool[(start + i) % pool.length]
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  categories,
+  excuse,
+  excuseBatch,
+  excuseReport
+});

package/index.d.cts

@@ -0,0 +1,30 @@
+export type Category =
+  | "deployment"
+  | "build"
+  | "production"
+  | "bug"
+  | "api"
+  | "database"
+  | "deadline"
+  | "testing"
+  | "network"
+  | "merge-conflict"
+  | "demo";
+export interface ExcuseOptions {
+  seed?: string | number;
+}
+export interface ExcuseReport {
+  category: Category;
+  excuse: string;
+  nextStep: string;
+}
+export function categories(): Category[];
+export function excuse(category?: Category, options?: ExcuseOptions): string;
+export function excuseBatch(
+  category?: Category,
+  options?: ExcuseOptions & { count?: number },
+): string[];
+export function excuseReport(
+  category?: Category,
+  options?: ExcuseOptions,
+): ExcuseReport;

package/index.d.ts

@@ -0,0 +1,30 @@
+export type Category =
+  | "deployment"
+  | "build"
+  | "production"
+  | "bug"
+  | "api"
+  | "database"
+  | "deadline"
+  | "testing"
+  | "network"
+  | "merge-conflict"
+  | "demo";
+export interface ExcuseOptions {
+  seed?: string | number;
+}
+export interface ExcuseReport {
+  category: Category;
+  excuse: string;
+  nextStep: string;
+}
+export function categories(): Category[];
+export function excuse(category?: Category, options?: ExcuseOptions): string;
+export function excuseBatch(
+  category?: Category,
+  options?: ExcuseOptions & { count?: number },
+): string[];
+export function excuseReport(
+  category?: Category,
+  options?: ExcuseOptions,
+): ExcuseReport;

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@deployanyway/excuse-js",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A seeded developer excuse generator for bugs, builds, and deployments. Finally, a dependency that takes the blame.",
   "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": {
     "excuse-js": "./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",
@@ -46,6 +71,12 @@
     "excuse-generator",
     "seeded",
     "developer-humor",
-    "deployment"
-  ]
+    "deployment",
+    "typescript",
+    "humor",
+    "deployanyway"
+  ],
+  "main": "./dist/index.cjs",
+  "types": "./index.d.ts",
+  "homepage": "https://deployanyway.github.io/"
 }

package/src/cli.js

@@ -0,0 +1,67 @@
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { URL } from "node:url";
+import { excuse, categories, excuseBatch, excuseReport } from "./index.js";
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      seed: { type: "string" },
+      list: { type: "boolean" },
+      count: { type: "string" },
+      json: { type: "boolean" },
+      report: { type: "boolean" },
+    },
+  });
+  if (values.help) {
+    console.log(
+      "Usage: excuse-js [category] [--seed text] [--count 3] [--json]\n\nDefault category: deployment. --report pairs the joke with an honest next step.\n\nOptions:\n  --seed text    Repeatable selection (always a string seed)\n  --count 1..20  Prepare a batch for the meeting\n  --json         Structured string or batch\n  --list         List categories\n  -h, --help     Show help\n  -v, --version  Show version\n\nExample: excuse-js deployment --seed demo\nExit codes: 0 success; 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) {
+    if (
+      positionals.length ||
+      values.seed !== undefined ||
+      values.count !== undefined ||
+      values.json ||
+      values.report
+    )
+      throw new TypeError("--list does not accept a category or seed.");
+    console.log(categories().join("\n"));
+  } else {
+    if (positionals.length > 1)
+      throw new TypeError("Provide only one category.");
+    if (values.count !== undefined && !/^[0-9]+$/.test(values.count))
+      throw new TypeError("count must be an integer.");
+    if (values.report && values.count !== undefined)
+      throw new TypeError("--report cannot be combined with --count.");
+    const result = values.report
+      ? excuseReport(positionals[0], { seed: values.seed })
+      : values.count === undefined
+        ? excuse(positionals[0], { seed: values.seed })
+        : excuseBatch(positionals[0], {
+            seed: values.seed,
+            count: Number(values.count),
+          });
+    console.log(
+      values.json
+        ? JSON.stringify(result)
+        : Array.isArray(result)
+          ? result.map((line, i) => `${i + 1}. ${line}`).join("\n")
+          : values.report
+            ? `${result.excuse}\nNext step: ${result.nextStep}`
+            : result,
+    );
+  }
+} catch (error) {
+  console.error(`excuse-js: ${error.message}\nRun with --help for usage.`);
+  process.exitCode = 2;
+}

package/src/index.js

@@ -1,4 +1,36 @@
 import { phrases } from "./excuses.js";
+const nextSteps = {
+  deployment:
+    "Check the release diff and rollback plan before delivering this line.",
+  testing:
+    "Reproduce the failure and add a regression test. The punchline is optional.",
+  build:
+    "Read the first build error, verify dependencies, then rebuild. The compiler does not accept applause.",
+  production:
+    "Check health metrics and the latest release diff; confirm rollback before improving the punchline.",
+  bug: "Save a minimal reproduction and add a regression test. The bug would prefer neither.",
+  api: "Inspect the status, payload and timeout contract. The endpoint is not communicating through vibes.",
+  database:
+    "Check connectivity and migration state before retrying. The data deserves a backup, not a speech.",
+  deadline:
+    "Name the smallest deliverable and communicate the revised estimate. Calendars cannot compile optimism.",
+  network:
+    "Check DNS, connectivity and timeout settings. Blame needs a packet capture.",
+  demo: "Rehearse the happy path and prepare an offline fallback. The projector can smell confidence.",
+};
+
+/** A comic excuse paired with an honest, actionable follow-up. */
+export function excuseReport(category = "deployment", options = {}) {
+  const text = excuse(category, options);
+  const key = category.trim().toLowerCase();
+  return {
+    category: key,
+    excuse: text,
+    nextStep:
+      nextSteps[key] ??
+      "Read the evidence, name an owner, and document the next small fix.",
+  };
+}
 
 /** Return the available lowercase category names as a fresh array. */
 export function categories() {