excuse-js

Own It: incident updates with accountable facts (1.0.0)

incidentUpdate(facts, options) drafts an honest status update from supplied service, impact, action, owner and nextUpdate. Missing fields stay explicit; it invents no impact, remediation, owner or ETA. Default public output contains no comic relief.

import { incidentUpdate } from "@deployanyway/excuse-js";
const update = incidentUpdate({
  status: "identified",
  service: "API",
  impact: "Some requests return 503",
  action: "Rolling back the latest release",
  owner: "On-call developer",
  nextUpdate: "2026-10-09T02:15:00Z",
});
if (!update.complete) console.error("Missing facts:", update.missing);
console.log(update.message); // draft only; no message is sent

Statuses: investigating (default), identified, monitoring, resolved. nextUpdate and optional now use UTC ISO timestamps. Missing unresolved nextUpdate is reported; a resolved status does not require a next update. overdue marks a scheduled update in the past. complete reflects required facts, not a verification that an incident is fixed. Strings are bounded and terminal control characters are removed. Result fields are copied and expose message/missing/complete/overdue.

For internal updates only, opt into {audience: 'internal', humor: true, seed: 'demo', category: 'production'}. Comic relief is labeled separately and leaves facts unchanged. Public + humor throws rather than quietly adding a joke. Internal jokes are original catalog content; exact wording is version-specific.

printf '%s' '{"service":"API","impact":"Some requests fail","action":"Investigating","owner":"On-call","nextUpdate":"2026-10-09T02:15:00Z"}' | excuse-js --incident --json --require-complete
node node_modules/@deployanyway/excuse-js/examples/own-it.mjs incident.json

--incident accepts JSON stdin (256 KiB), --audience public/internal, --humor, --seed, --now and --json. --require-complete exits 1 when facts are missing; default draft output exits 0 and invalid input exits 2. Neither the API nor CLI posts an update. Review facts before sharing.

Stable v1 contract

Node 22.13+ or Node 24. MIT licensed. CLI flags, structured fields, ESM/CommonJS exports and declarations are covered by tests and installed-package checks. Existing 0.4 APIs remain available except the explicitly documented doggo-log redaction/text-context changes. Future incompatible public API changes require a major release; callers should consume structured fields rather than parse jokes. Exact humorous wording and seeded catalog choices are version-specific. No telemetry, external API keys or network service is needed for core use.

Run npm test, npm run lint, npm run format:check, npm run coverage, npm run test:types and npm run verify:package from a source checkout. Runnable examples are shipped under examples/. The root demo is https://deployanyway.github.io/.

A meeting-sized library (0.4.0)

132 original workplace-safe excuses: twelve distinct phrases in each of eleven categories. Seeded batches avoid repeats until all twelve phrases in the category have been used; larger batches cycle. Reports pair the joke with an honest next step. The jokes are for humor, not hiding incidents or misleading teammates.

npx @deployanyway/excuse-js testing --count 12 --seed demo
npx @deployanyway/excuse-js production --report --seed demo
npx @deployanyway/excuse-js network --catalog --json

import {
  listExcuses,
  excuseBatch,
  excuseReport,
} from "@deployanyway/excuse-js";
console.log(listExcuses("testing"));
console.log(excuseBatch("demo", { count: 5, seed: "rehearsal" }));
console.log(excuseReport("production", { seed: "incident" }));

listExcuses(category?) returns a fresh copy of the category catalog without consuming randomness. CLI --catalog accepts a category and optional --json, not seed, count or report. Catalog expansion changes which phrase a seed chooses compared with 0.3.0; pin the version for exact reproducibility.

Version 0.4.0: install from npm with Node 22.13+ or Node 24. See MIGRATION.md for changes from 0.2.0.

A seeded developer excuse generator for bugs, builds, and deployments. Finally, a dependency that takes the blame.

The edge case moved to the center and brought furniture.

Installation

Available on npm. Requires Node 22 or later. You can also run from source with Node 22 or 24:

git clone https://github.com/DeployAnyway/excuse-js.git
cd excuse-js
git checkout main
npm ci
node bin/cli.js bug

Install from npm: npm install @deployanyway/excuse-js.

Quick start

import { excuse, categories } from "@deployanyway/excuse-js";

console.log(excuse("deployment"));
console.log(excuse("bug", { seed: "demo" }));
console.log(categories());

CLI example

node bin/cli.js deployment --seed demo

Run with npx: npx @deployanyway/excuse-js deployment --seed demo.

API and options

excuse(category = 'deployment', { seed } = {}) returns a string. Category names are trimmed and case insensitive. Unknown categories throw RangeError. Invalid categories, options, and seeds throw TypeError. The library never exits or logs.

seed accepts a string (including empty string) or a finite number (including zero). Without a seed, selection uses Math.random. With a seed, selection uses FNV-1a over the UTF-16 code units of category:type:seed, then takes the unsigned hash modulo the phrase count. String and numeric seeds are distinct. Calls have no shared seed state; the same inputs select the same phrase within this version. Different seeds can select the same phrase. Seeded output can change when the catalog changes between versions; this is not a cryptographic generator.

categories() returns a fresh array of available lowercase names.

Categories

deployment, build, production, bug, api, database, deadline, testing, network, merge-conflict, demo. Each has twelve original, workplace-safe phrases.

Custom runtime categories are deferred. Contributors can extend the data file without changing the selection logic.

CLI reference

excuse-js [category] [options]

Option	Behavior
--seed text	Deterministic selection; CLI seeds are always strings
--list	Print category names; cannot combine with category or seed
--help, -h	Show help
--version, -v	Show version

No category defaults to deployment. Quote seeds containing spaces. Exit code 0 means success; 2 means invalid arguments. No stdin support in this MVP.

Examples and development

npm ci
node examples/basic.js
npm run lint
npm run format:check
npm test
npm pack --dry-run

ES modules, Node's built-in test runner, zero production dependencies. CI runs Node 22/24. ESLint development requires Node 22.13+ or 24. Phrases are in src/excuses.js, API in src/index.js, and CLI in bin/cli.js.

Contributing

See CONTRIBUTING.md. Useful first, funny second.

License

MIT.

More from DeployAnyway

Tools for developers who probably know better.

• error-translator
• excuse-js
• doggo-log
• ship-it-meter
• bro-say

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.

npx @deployanyway/excuse-js deployment --count 3 --seed demo

API (import the named functions from this package):

excuseBatch("deployment", { count: 3, seed: "demo" });

Jokes with a useful exit strategy

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".

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

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 · Conduct · Security · Roadmap · Migration.

Tools for developers who probably know better. Software nobody requested, built with questionable priorities, and shipped with absolute confidence!