@deployanyway/doggo-log 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.0
+
+48 original lines: eight per log level. Default `barkMode: 'classic'` preserves the existing first-line commentary. Opt into `barkMode: 'rotate'` for variation without repeats until that level's eight lines have been emitted. A seed selects a repeatable starting point by prefix and level; omitted seed starts with the first line. Filtering and quiet mode do not consume rotation. Each child logger owns its own sequence.
+
+```sh
+
+
 ## 0.3.0 — 2026-10-08
 
 - Useful structured API/CLI additions described in README.
@@ -22,3 +29,4 @@
 - Six logging methods, level filtering, quiet mode, and custom prefixes.
 - Optional emojis, ANSI colors, timestamps, and JSON output.
 - CLI, tests, documentation, and Node 22/24 CI.
+```

package/MIGRATION.md

@@ -3,3 +3,9 @@
 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
+
+48 original commentary lines across six levels; opt-in seeded rotation; independent child sequences, no advancement on filtering or failed writes; barkLines catalog API and CLI controls. Classic commentary remains default.
+
+Existing defaults and entry points remain available. The new commentary rotation is opt-in; classic first-line commentary remains the default.

package/README.md

@@ -1,6 +1,31 @@
 # doggo-log
 
-> **Version 0.3.0:** install from npm with Node 22.13+ or Node 24. See MIGRATION.md for changes from 0.2.0.
+## Commentary that stays useful (0.4.0)
+
+48 original lines: eight per log level. Default `barkMode: 'classic'` preserves the existing first-line commentary. Opt into `barkMode: 'rotate'` for variation without repeats until that level's eight lines have been emitted. A seed selects a repeatable starting point by prefix and level; omitted seed starts with the first line. Filtering and quiet mode do not consume rotation. Each child logger owns its own sequence.
+
+```sh
+npx @deployanyway/doggo-log warn 'Retry budget almost exhausted' --bark --bark-mode rotate --seed demo --json
+```
+
+```js
+import { createDogLogger, barkLines } from "@deployanyway/doggo-log";
+const log = createDogLogger({
+  bark: true,
+  barkMode: "rotate",
+  seed: "job-42",
+  json: true,
+});
+const job = log.child("worker", { jobId: "42" });
+job.info("Job accepted");
+job.warn("Retry budget almost exhausted");
+job.success("Job complete");
+console.log(barkLines("warn"));
+```
+
+Caller messages and JSON context remain separate from commentary. `barkLines(level)` returns a fresh catalog copy. The logger is intentionally small: it does not provide persistence, transport, redaction or a production observability backend.
+
+> **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%2Fdoggo-log)](https://www.npmjs.com/package/@deployanyway/doggo-log)
 [![CI](https://github.com/DeployAnyway/doggo-log/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DeployAnyway/doggo-log/actions/workflows/ci.yml)

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var index_exports = {};
 __export(index_exports, {
+  barkLines: () => barkLines,
   createDogLogger: () => createDogLogger,
   doglog: () => doglog
 });
@@ -36,21 +37,93 @@ var levels = {
   error: { rank: 40, emoji: "\u{1F6A8}", color: 31 }
 };
 
-// src/index.js
-var barks = {
-  debug: "Sniffing for clues.",
-  log: "Filed under things I sniffed.",
-  info: "Good to know. Good dog to tell you.",
-  success: "Treat budget approved.",
-  warn: "Suspicious squirrel detected.",
-  error: "The dog has fetched the incident report."
+// src/commentary.js
+var lines = {
+  debug: [
+    "Sniffing for clues.",
+    "Follow the trace, not the squirrel.",
+    "One breakpoint. Two ears. Maximum attention.",
+    "The missing value has left a scent trail.",
+    "Logging the evidence before chasing the theory.",
+    "The stack trace is our walking route.",
+    "Small reproduction, big detective energy.",
+    "Dallas found a clue. Benji would like to inspect the keyboard."
+  ],
+  log: [
+    "Filed under things I sniffed.",
+    "Fetch complete. Filing the interesting bit.",
+    "Another breadcrumb for future-us.",
+    "This line has been approved by the tail department.",
+    "A small update with excellent ears.",
+    "Evidence delivered without chewing it.",
+    "Keeping a trail through the code forest.",
+    "Benji brought the log. Dallas brought enthusiasm."
+  ],
+  info: [
+    "Good to know. Good dog to tell you.",
+    "A useful update, delivered at husky speed.",
+    "The facts have arrived wearing sensible paws.",
+    "Worth knowing before the next zoomie.",
+    "No alarm. Just a well-timed nose boop.",
+    "Status fetched. Tail at a responsible speed.",
+    "A little context saves a lot of barking.",
+    "Dallas and Benji have entered the observability business."
+  ],
+  success: [
+    "Treat budget approved.",
+    "Good result. Better evidence. Best dog.",
+    "The check passed. Save some applause for monitoring.",
+    "One fewer problem between us and the walk.",
+    "Tail deployment successful.",
+    "The happy path has receipts today.",
+    "Achievement unlocked: boring, repeatable success.",
+    "Dallas celebrates. Benji is already planning the victory lap."
+  ],
+  warn: [
+    "Suspicious squirrel detected.",
+    "Ears up. This deserves a closer look.",
+    "Something smells odd; inspect before retrying.",
+    "A warning is a breadcrumb, not a dare.",
+    "The tail slowed down for a reason.",
+    "Check the evidence before this becomes an incident.",
+    "Potential trouble has arrived with muddy paws.",
+    "Benji heard something. Dallas recommends checking the logs."
+  ],
+  error: [
+    "The dog has fetched the incident report.",
+    "Read the first failure before chasing the pack.",
+    "The red light is evidence, not a personality review.",
+    "Pause the zoomies. Find the cause and the rollback.",
+    "This needs a fix, not louder barking.",
+    "Capture the reproduction while the scent is fresh.",
+    "The operation failed. The team still gets kindness.",
+    "Dallas and Benji are standing by with emotional support."
+  ]
 };
+function barkLines(level) {
+  if (typeof level !== "string" || !Object.hasOwn(lines, level))
+    throw new RangeError("Choose debug, log, info, success, warn or error.");
+  return [...lines[level]];
+}
+function commentaryIndex(seed, salt, length) {
+  if (seed === void 0) return 0;
+  let hash = 2166136261;
+  for (const char of salt + ":" + typeof seed + ":" + seed) {
+    hash ^= char.codePointAt(0);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash % length;
+}
+
+// src/index.js
 function createDogLogger(options = {}) {
   if (!options || typeof options !== "object" || Array.isArray(options))
     throw new TypeError("Options must be an object.");
   const config = {
     emoji: true,
     bark: false,
+    barkMode: "classic",
+    seed: void 0,
     color: false,
     timestamp: false,
     json: false,
@@ -82,6 +155,11 @@ function createDogLogger(options = {}) {
     );
   if (typeof config.write !== "function" || typeof config.clock !== "function")
     throw new TypeError("write and clock must be functions.");
+  if (!["classic", "rotate"].includes(config.barkMode))
+    throw new RangeError("barkMode must be classic or rotate.");
+  if (config.seed !== void 0 && typeof config.seed !== "string" && !(typeof config.seed === "number" && Number.isFinite(config.seed)))
+    throw new TypeError("seed must be a string or finite number.");
+  const counters = {};
   const logger = Object.fromEntries(
     Object.entries(levels).map(([level, style]) => [
       level,
@@ -89,7 +167,13 @@ function createDogLogger(options = {}) {
         if (config.quiet || style.rank < levels[config.level].rank)
           return void 0;
         const message = (0, import_node_util.format)(...args);
-        const commentary = config.bark ? barks[level] : void 0;
+        const pool = config.bark ? barkLines(level) : void 0;
+        const index = config.barkMode === "rotate" ? (commentaryIndex(
+          config.seed,
+          config.prefix + ":" + level,
+          pool?.length ?? 1
+        ) + (counters[level] ?? 0)) % (pool?.length ?? 1) : 0;
+        const commentary = pool?.[index];
         let timestamp;
         if (config.timestamp) {
           const date = config.clock();
@@ -119,6 +203,8 @@ function createDogLogger(options = {}) {
           if (config.color) line = `\x1B[${style.color}m${line}\x1B[0m`;
         }
         config.write(line, level);
+        if (config.bark)
+          counters[level] = ((counters[level] ?? 0) + 1) % pool.length;
         return line;
       }
     ])
@@ -147,6 +233,7 @@ function createDogLogger(options = {}) {
 var doglog = createDogLogger();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  barkLines,
   createDogLogger,
   doglog
 });

package/index.d.cts

@@ -3,6 +3,8 @@ export type LogContext = Record<string, string | number | boolean | null>;
 export interface DogOptions {
   emoji?: boolean;
   bark?: boolean;
+  barkMode?: "classic" | "rotate";
+  seed?: string | number;
   color?: boolean;
   timestamp?: boolean;
   json?: boolean;
@@ -20,3 +22,5 @@ export type DogLogger = Record<Level, LogMethod> & {
 };
 export function createDogLogger(options?: DogOptions): DogLogger;
 export const doglog: DogLogger;
+
+export function barkLines(level: Level): string[];

package/index.d.ts

@@ -3,6 +3,8 @@ export type LogContext = Record<string, string | number | boolean | null>;
 export interface DogOptions {
   emoji?: boolean;
   bark?: boolean;
+  barkMode?: "classic" | "rotate";
+  seed?: string | number;
   color?: boolean;
   timestamp?: boolean;
   json?: boolean;
@@ -20,3 +22,5 @@ export type DogLogger = Record<Level, LogMethod> & {
 };
 export function createDogLogger(options?: DogOptions): DogLogger;
 export const doglog: DogLogger;
+
+export function barkLines(level: Level): string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deployanyway/doggo-log",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A tiny Node.js console logger with JSON output, log levels, and dog emojis. Good logs. Very good logs.",
   "type": "module",
   "exports": {

package/src/cli.js

@@ -17,6 +17,8 @@ try {
       context: { type: "string" },
       "no-color": { type: "boolean" },
       bark: { type: "boolean" },
+      "bark-mode": { type: "string" },
+      seed: { type: "string" },
       timestamp: { type: "boolean" },
       quiet: { type: "boolean" },
       color: { type: "boolean" },
@@ -27,7 +29,7 @@ try {
   });
   if (values.help) {
     console.log(
-      "Usage: doggo-log <method> <message> [options]\n\nMethods: log, info, success, warn, error, debug. --stdin reads a bounded message; arguments win. --context accepts JSON scalar fields for JSON logs; --no-color and NO_COLOR disable ANSI.\nOptions:\n  --bark         Add useful dog commentary\n  --json         Emit JSON\n  --timestamp    Include an ISO timestamp\n  --no-emoji     Disable emojis\n  --color        Enable ANSI colors\n  --prefix text  Add a prefix\n  --level name   Minimum level (CLI default: debug)\n  --quiet        Suppress output\n  -h, --help     Show help\n  -v, --version  Show version\n\nExit codes: 0 success; 2 invalid arguments. Logging an error exits 0.",
+      "Usage: doggo-log <method> <message> [options]\n\nMethods: log, info, success, warn, error, debug. --stdin reads a bounded message; arguments win. --context accepts JSON scalar fields for JSON logs; --no-color and NO_COLOR disable ANSI.\nOptions:\n  --bark         Add useful dog commentary\n  --bark-mode classic|rotate  Classic line or varied commentary\n  --seed text    Repeatable rotation starting point\n  --json         Emit JSON\n  --timestamp    Include an ISO timestamp\n  --no-emoji     Disable emojis\n  --color        Enable ANSI colors\n  --prefix text  Add a prefix\n  --level name   Minimum level (CLI default: debug)\n  --quiet        Suppress output\n  -h, --help     Show help\n  -v, --version  Show version\n\nExit codes: 0 success; 2 invalid arguments. Logging an error exits 0.",
     );
   } else if (values.version) {
     console.log(
@@ -47,6 +49,8 @@ try {
     const logger = createDogLogger({
       emoji: !values["no-emoji"],
       bark: values.bark ?? false,
+      barkMode: values["bark-mode"] ?? "classic",
+      seed: values.seed,
       color:
         !values["no-color"] &&
         !Object.hasOwn(process.env, "NO_COLOR") &&

package/src/commentary.js

@@ -0,0 +1,77 @@
+// Original commentary; never replaces the caller's message.
+const lines = {
+  debug: [
+    "Sniffing for clues.",
+    "Follow the trace, not the squirrel.",
+    "One breakpoint. Two ears. Maximum attention.",
+    "The missing value has left a scent trail.",
+    "Logging the evidence before chasing the theory.",
+    "The stack trace is our walking route.",
+    "Small reproduction, big detective energy.",
+    "Dallas found a clue. Benji would like to inspect the keyboard.",
+  ],
+  log: [
+    "Filed under things I sniffed.",
+    "Fetch complete. Filing the interesting bit.",
+    "Another breadcrumb for future-us.",
+    "This line has been approved by the tail department.",
+    "A small update with excellent ears.",
+    "Evidence delivered without chewing it.",
+    "Keeping a trail through the code forest.",
+    "Benji brought the log. Dallas brought enthusiasm.",
+  ],
+  info: [
+    "Good to know. Good dog to tell you.",
+    "A useful update, delivered at husky speed.",
+    "The facts have arrived wearing sensible paws.",
+    "Worth knowing before the next zoomie.",
+    "No alarm. Just a well-timed nose boop.",
+    "Status fetched. Tail at a responsible speed.",
+    "A little context saves a lot of barking.",
+    "Dallas and Benji have entered the observability business.",
+  ],
+  success: [
+    "Treat budget approved.",
+    "Good result. Better evidence. Best dog.",
+    "The check passed. Save some applause for monitoring.",
+    "One fewer problem between us and the walk.",
+    "Tail deployment successful.",
+    "The happy path has receipts today.",
+    "Achievement unlocked: boring, repeatable success.",
+    "Dallas celebrates. Benji is already planning the victory lap.",
+  ],
+  warn: [
+    "Suspicious squirrel detected.",
+    "Ears up. This deserves a closer look.",
+    "Something smells odd; inspect before retrying.",
+    "A warning is a breadcrumb, not a dare.",
+    "The tail slowed down for a reason.",
+    "Check the evidence before this becomes an incident.",
+    "Potential trouble has arrived with muddy paws.",
+    "Benji heard something. Dallas recommends checking the logs.",
+  ],
+  error: [
+    "The dog has fetched the incident report.",
+    "Read the first failure before chasing the pack.",
+    "The red light is evidence, not a personality review.",
+    "Pause the zoomies. Find the cause and the rollback.",
+    "This needs a fix, not louder barking.",
+    "Capture the reproduction while the scent is fresh.",
+    "The operation failed. The team still gets kindness.",
+    "Dallas and Benji are standing by with emotional support.",
+  ],
+};
+export function barkLines(level) {
+  if (typeof level !== "string" || !Object.hasOwn(lines, level))
+    throw new RangeError("Choose debug, log, info, success, warn or error.");
+  return [...lines[level]];
+}
+export function commentaryIndex(seed, salt, length) {
+  if (seed === undefined) return 0;
+  let hash = 2166136261;
+  for (const char of salt + ":" + typeof seed + ":" + seed) {
+    hash ^= char.codePointAt(0);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash % length;
+}

package/src/index.js

@@ -1,13 +1,7 @@
 import { format } from "node:util";
 import { levels } from "./levels.js";
-const barks = {
-  debug: "Sniffing for clues.",
-  log: "Filed under things I sniffed.",
-  info: "Good to know. Good dog to tell you.",
-  success: "Treat budget approved.",
-  warn: "Suspicious squirrel detected.",
-  error: "The dog has fetched the incident report.",
-};
+import { barkLines, commentaryIndex } from "./commentary.js";
+export { barkLines };
 
 /**
  * Create a small logger. Methods return the emitted line, or undefined if filtered.
@@ -19,6 +13,8 @@ export function createDogLogger(options = {}) {
   const config = {
     emoji: true,
     bark: false,
+    barkMode: "classic",
+    seed: undefined,
     color: false,
     timestamp: false,
     json: false,
@@ -62,6 +58,15 @@ export function createDogLogger(options = {}) {
     );
   if (typeof config.write !== "function" || typeof config.clock !== "function")
     throw new TypeError("write and clock must be functions.");
+  if (!["classic", "rotate"].includes(config.barkMode))
+    throw new RangeError("barkMode must be classic or rotate.");
+  if (
+    config.seed !== undefined &&
+    typeof config.seed !== "string" &&
+    !(typeof config.seed === "number" && Number.isFinite(config.seed))
+  )
+    throw new TypeError("seed must be a string or finite number.");
+  const counters = {};
   const logger = Object.fromEntries(
     Object.entries(levels).map(([level, style]) => [
       level,
@@ -69,7 +74,18 @@ export function createDogLogger(options = {}) {
         if (config.quiet || style.rank < levels[config.level].rank)
           return undefined;
         const message = format(...args);
-        const commentary = config.bark ? barks[level] : undefined;
+        const pool = config.bark ? barkLines(level) : undefined;
+        const index =
+          config.barkMode === "rotate"
+            ? (commentaryIndex(
+                config.seed,
+                config.prefix + ":" + level,
+                pool?.length ?? 1,
+              ) +
+                (counters[level] ?? 0)) %
+              (pool?.length ?? 1)
+            : 0;
+        const commentary = pool?.[index];
         let timestamp;
         if (config.timestamp) {
           const date = config.clock();
@@ -103,6 +119,8 @@ export function createDogLogger(options = {}) {
           if (config.color) line = `\u001b[${style.color}m${line}\u001b[0m`;
         }
         config.write(line, level);
+        if (config.bark)
+          counters[level] = ((counters[level] ?? 0) + 1) % pool.length;
         return line;
       },
     ]),