@deployanyway/excuse-js 0.4.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.0.0
+
+- Own It: incident updates with accountable facts.
+- Typed API, CLI integration, runnable codebase example and meaningful workflow tests.
+- Stable contracts and migration guidance; original humor stays around accurate facts.
+
 ## 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.

package/MIGRATION.md

@@ -9,3 +9,9 @@ Install 0.3.0 with npm. Seeds and exact humorous wording are version-specific. D
 132 original phrases across eleven categories; twelve unique items before batch cycling; independent listExcuses catalogs and CLI --catalog; specific conflict-resolution next step.
 
 Seeded selections are version-specific and may differ after catalog expansion. Pin the version for exact reproducibility. Existing user messages and API entry points remain supported.
+
+## 0.4.0 to stable 1.0.0
+
+Incident drafting is additive and does not change seeded excuse APIs. Public incident output defaults to humor off. Existing excuse/--report behavior remains explicitly humorous.
+
+See README for exact contracts, bounds and failure behavior.

package/README.md

@@ -1,5 +1,40 @@
 # 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.
+
+```js
+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.
+
+```sh
+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.

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   excuse: () => excuse,
   excuseBatch: () => excuseBatch,
   excuseReport: () => excuseReport,
+  incidentUpdate: () => incidentUpdate,
   listExcuses: () => listExcuses
 });
 module.exports = __toCommonJS(index_exports);
@@ -186,6 +187,62 @@ var phrases = {
   ]
 };
 
+// src/incident.js
+var iso = (value, label) => {
+  if (typeof value !== "string" || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/.test(value) || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString().slice(0, 19) !== value.slice(0, 19))
+    throw new TypeError(`${label} must be a UTC ISO timestamp.`);
+  return value;
+};
+var clean = (value) => Array.from(value).filter(
+  (char) => char.charCodeAt(0) >= 32 || char === "\n" || char === "	"
+).join("");
+function incidentUpdate(facts = {}, options = {}) {
+  if (!facts || typeof facts !== "object" || Array.isArray(facts))
+    throw new TypeError("Incident facts must be an object.");
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Options must be an object.");
+  const status = facts.status ?? "investigating", audience = options.audience ?? "public", humor = options.humor ?? false;
+  if (!["investigating", "identified", "monitoring", "resolved"].includes(status))
+    throw new RangeError("Unsupported incident status.");
+  if (!["public", "internal"].includes(audience) || typeof humor !== "boolean")
+    throw new TypeError("Choose public/internal audience and boolean humor.");
+  if (humor && audience !== "internal")
+    throw new TypeError("Comic relief requires an internal audience.");
+  const result = { status, audience, missing: [], overdue: false };
+  for (const key of ["service", "impact", "action", "owner"]) {
+    if (facts[key] !== void 0 && facts[key] !== null && (typeof facts[key] !== "string" || !facts[key].trim() || facts[key].length > 2e3))
+      throw new TypeError(
+        `${key} must be a nonempty string up to 2000 characters.`
+      );
+    result[key] = facts[key] === void 0 || facts[key] === null ? null : clean(facts[key].trim());
+    if (result[key] === null) result.missing.push(key);
+  }
+  const now = iso(options.now ?? (/* @__PURE__ */ new Date()).toISOString(), "now");
+  result.nextUpdate = facts.nextUpdate === void 0 || facts.nextUpdate === null ? null : iso(facts.nextUpdate, "nextUpdate");
+  if (result.nextUpdate === null && status !== "resolved")
+    result.missing.push("nextUpdate");
+  result.overdue = status !== "resolved" && result.nextUpdate !== null && Date.parse(result.nextUpdate) < Date.parse(now);
+  const lines = [
+    `Status: ${status}`,
+    `Service: ${result.service ?? "Not provided"}`,
+    `Impact: ${result.impact ?? "Not provided \u2014 verify before claiming an impact"}`,
+    `Current action: ${result.action ?? "Not provided"}`,
+    `Owner: ${result.owner ?? "Not assigned"}`,
+    `Next update: ${result.nextUpdate ?? (status === "resolved" ? "Not scheduled (status marked resolved)" : "Not scheduled")}${result.overdue ? " \u2014 OVERDUE" : ""}`
+  ];
+  if (result.missing.length)
+    lines.push("Missing facts: " + result.missing.join(", "));
+  result.complete = result.missing.length === 0;
+  if (humor) {
+    result.comicRelief = excuse(options.category ?? "production", {
+      seed: options.seed
+    });
+    lines.push("\nComic relief (internal only): " + result.comicRelief);
+  }
+  result.message = lines.join("\n");
+  return result;
+}
+
 // src/index.js
 var nextSteps = {
   "merge-conflict": "Understand both changes, resolve the conflict deliberately, then run tests for the combined behavior. Git does not accept a coin toss.",
@@ -267,5 +324,6 @@ function listExcuses(category = "deployment") {
   excuse,
   excuseBatch,
   excuseReport,
+  incidentUpdate,
   listExcuses
 });

package/examples/basic.js

@@ -0,0 +1,4 @@
+import { excuse, categories } from "@deployanyway/excuse-js";
+
+console.log(excuse("deployment", { seed: "demo" }));
+console.log(categories());

package/examples/own-it.mjs

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { incidentUpdate } from "@deployanyway/excuse-js";
+try {
+  const facts = process.argv[2]
+    ? JSON.parse(readFileSync(process.argv[2], "utf8"))
+    : {};
+  const draft = incidentUpdate(facts);
+  console.log(draft.message);
+  process.exitCode = draft.complete ? 0 : 1;
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 2;
+}

package/index.d.cts

@@ -30,3 +30,37 @@ export function excuseReport(
 ): ExcuseReport;
 
 export function listExcuses(category?: Category): string[];
+export type IncidentStatus =
+  "investigating" | "identified" | "monitoring" | "resolved";
+export interface IncidentFacts {
+  status?: IncidentStatus;
+  service?: string | null;
+  impact?: string | null;
+  action?: string | null;
+  owner?: string | null;
+  nextUpdate?: string | null;
+}
+export interface IncidentOptions extends ExcuseOptions {
+  audience?: "public" | "internal";
+  humor?: boolean;
+  category?: Category;
+  now?: string;
+}
+export interface IncidentUpdate {
+  complete: boolean;
+  status: IncidentStatus;
+  audience: "public" | "internal";
+  service: string | null;
+  impact: string | null;
+  action: string | null;
+  owner: string | null;
+  nextUpdate: string | null;
+  missing: string[];
+  overdue: boolean;
+  comicRelief?: string;
+  message: string;
+}
+export function incidentUpdate(
+  facts?: IncidentFacts,
+  options?: IncidentOptions,
+): IncidentUpdate;

package/index.d.ts

@@ -30,3 +30,37 @@ export function excuseReport(
 ): ExcuseReport;
 
 export function listExcuses(category?: Category): string[];
+export type IncidentStatus =
+  "investigating" | "identified" | "monitoring" | "resolved";
+export interface IncidentFacts {
+  status?: IncidentStatus;
+  service?: string | null;
+  impact?: string | null;
+  action?: string | null;
+  owner?: string | null;
+  nextUpdate?: string | null;
+}
+export interface IncidentOptions extends ExcuseOptions {
+  audience?: "public" | "internal";
+  humor?: boolean;
+  category?: Category;
+  now?: string;
+}
+export interface IncidentUpdate {
+  complete: boolean;
+  status: IncidentStatus;
+  audience: "public" | "internal";
+  service: string | null;
+  impact: string | null;
+  action: string | null;
+  owner: string | null;
+  nextUpdate: string | null;
+  missing: string[];
+  overdue: boolean;
+  comicRelief?: string;
+  message: string;
+}
+export function incidentUpdate(
+  facts?: IncidentFacts,
+  options?: IncidentOptions,
+): IncidentUpdate;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deployanyway/excuse-js",
-  "version": "0.4.0",
-  "description": "A seeded developer excuse generator for bugs, builds, and deployments. Finally, a dependency that takes the blame.",
+  "version": "1.0.0",
+  "description": "Seeded developer humor and factual incident status updates with owners and next steps. Finally, a dependency that takes the blame responsibly.",
   "type": "module",
   "exports": {
     ".": {
@@ -27,7 +27,8 @@
     "dist",
     "index.d.ts",
     "index.d.cts",
-    "MIGRATION.md"
+    "MIGRATION.md",
+    "examples"
   ],
   "engines": {
     "node": ">=22.13"
@@ -74,7 +75,9 @@
     "deployment",
     "typescript",
     "humor",
-    "deployanyway"
+    "deployanyway",
+    "incident-update",
+    "status-update"
   ],
   "main": "./dist/index.cjs",
   "types": "./index.d.ts",

package/src/cli.js

@@ -7,7 +7,9 @@ import {
   excuseBatch,
   excuseReport,
   listExcuses,
+  incidentUpdate,
 } from "./index.js";
+import { readStdin } from "./input.js";
 
 try {
   const { values, positionals } = parseArgs({
@@ -21,11 +23,16 @@ try {
       json: { type: "boolean" },
       report: { type: "boolean" },
       catalog: { type: "boolean" },
+      incident: { type: "boolean" },
+      "require-complete": { type: "boolean" },
+      audience: { type: "string" },
+      humor: { type: "boolean" },
+      now: { type: "string" },
     },
   });
   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  --catalog      Show every phrase in a category\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.",
+      "Usage: excuse-js [category] [--seed text] [--count 3] [--json]\n\n--incident reads factual incident JSON from stdin. --audience public|internal, --humor (internal only), --now UTC-ISO and --require-complete support accountable drafts. No message is sent.\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  --catalog      Show every phrase in a category\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/draft; 1 incomplete required incident; 2 invalid arguments.",
     );
   } else if (values.version) {
     console.log(
@@ -33,6 +40,32 @@ try {
         readFileSync(new URL("../package.json", import.meta.url), "utf8"),
       ).version,
     );
+  } else if (values.incident) {
+    if (
+      positionals.length ||
+      values.list ||
+      values.catalog ||
+      values.report ||
+      values.count !== undefined
+    )
+      throw new TypeError(
+        "--incident reads JSON stdin and cannot combine with category, list, catalog, report or count.",
+      );
+    const result = incidentUpdate(JSON.parse(await readStdin()), {
+      audience: values.audience ?? "public",
+      humor: values.humor ?? false,
+      seed: values.seed,
+      ...(values.now !== undefined ? { now: values.now } : {}),
+    });
+    console.log(values.json ? JSON.stringify(result, null, 2) : result.message);
+    if (values["require-complete"] && !result.complete) process.exitCode = 1;
+  } else if (
+    values.audience !== undefined ||
+    values.humor ||
+    values.now !== undefined ||
+    values["require-complete"]
+  ) {
+    throw new TypeError("--audience, --humor and --now require --incident.");
   } else if (values.list) {
     if (
       positionals.length ||

package/src/incident.js

@@ -0,0 +1,83 @@
+import { excuse } from "./index.js";
+const iso = (value, label) => {
+  if (
+    typeof value !== "string" ||
+    !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/.test(value) ||
+    !Number.isFinite(Date.parse(value)) ||
+    new Date(value).toISOString().slice(0, 19) !== value.slice(0, 19)
+  )
+    throw new TypeError(`${label} must be a UTC ISO timestamp.`);
+  return value;
+};
+const clean = (value) =>
+  Array.from(value)
+    .filter(
+      (char) => char.charCodeAt(0) >= 32 || char === "\n" || char === "\t",
+    )
+    .join("");
+/** Draft factual incident communication; public output never adds a joke. */
+export function incidentUpdate(facts = {}, options = {}) {
+  if (!facts || typeof facts !== "object" || Array.isArray(facts))
+    throw new TypeError("Incident facts must be an object.");
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Options must be an object.");
+  const status = facts.status ?? "investigating",
+    audience = options.audience ?? "public",
+    humor = options.humor ?? false;
+  if (
+    !["investigating", "identified", "monitoring", "resolved"].includes(status)
+  )
+    throw new RangeError("Unsupported incident status.");
+  if (!["public", "internal"].includes(audience) || typeof humor !== "boolean")
+    throw new TypeError("Choose public/internal audience and boolean humor.");
+  if (humor && audience !== "internal")
+    throw new TypeError("Comic relief requires an internal audience.");
+  const result = { status, audience, missing: [], overdue: false };
+  for (const key of ["service", "impact", "action", "owner"]) {
+    if (
+      facts[key] !== undefined &&
+      facts[key] !== null &&
+      (typeof facts[key] !== "string" ||
+        !facts[key].trim() ||
+        facts[key].length > 2000)
+    )
+      throw new TypeError(
+        `${key} must be a nonempty string up to 2000 characters.`,
+      );
+    result[key] =
+      facts[key] === undefined || facts[key] === null
+        ? null
+        : clean(facts[key].trim());
+    if (result[key] === null) result.missing.push(key);
+  }
+  const now = iso(options.now ?? new Date().toISOString(), "now");
+  result.nextUpdate =
+    facts.nextUpdate === undefined || facts.nextUpdate === null
+      ? null
+      : iso(facts.nextUpdate, "nextUpdate");
+  if (result.nextUpdate === null && status !== "resolved")
+    result.missing.push("nextUpdate");
+  result.overdue =
+    status !== "resolved" &&
+    result.nextUpdate !== null &&
+    Date.parse(result.nextUpdate) < Date.parse(now);
+  const lines = [
+    `Status: ${status}`,
+    `Service: ${result.service ?? "Not provided"}`,
+    `Impact: ${result.impact ?? "Not provided — verify before claiming an impact"}`,
+    `Current action: ${result.action ?? "Not provided"}`,
+    `Owner: ${result.owner ?? "Not assigned"}`,
+    `Next update: ${result.nextUpdate ?? (status === "resolved" ? "Not scheduled (status marked resolved)" : "Not scheduled")}${result.overdue ? " — OVERDUE" : ""}`,
+  ];
+  if (result.missing.length)
+    lines.push("Missing facts: " + result.missing.join(", "));
+  result.complete = result.missing.length === 0;
+  if (humor) {
+    result.comicRelief = excuse(options.category ?? "production", {
+      seed: options.seed,
+    });
+    lines.push("\nComic relief (internal only): " + result.comicRelief);
+  }
+  result.message = lines.join("\n");
+  return result;
+}

package/src/index.js

@@ -102,3 +102,4 @@ export function listExcuses(category = "deployment") {
     throw new RangeError("Unknown category: " + category);
   return [...phrases[key]];
 }
+export { incidentUpdate } from "./incident.js";

package/src/input.js

@@ -0,0 +1,15 @@
+/** Bounded UTF-8 input for incident facts, independent of terminal output. */
+export async function readStdin(stream = process.stdin) {
+  if (stream.isTTY) throw new TypeError("Pipe incident facts as JSON.");
+  let size = 0;
+  const chunks = [];
+  for await (const chunk of stream) {
+    const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    size += bytes.length;
+    if (size > 262144) throw new RangeError("stdin exceeds 256 KiB.");
+    chunks.push(bytes);
+  }
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (!text.trim()) throw new TypeError("Provide incident facts as JSON.");
+  return text;
+}