@deployanyway/doggo-log 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 — Unreleased
+
+- 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deploy Anyway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,141 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+# doggo-log
+
+A tiny dog-themed logger with useful output and good manners.
+
+```text
+🐶 INFO    Server started
+🐾 SUCCESS Tests passed
+🦴 WARN    API is getting slow
+🚨 ERROR   Database connection failed
+```
+
+## Installation
+
+Version 0.1.0 has not been published to npm. Try from source with Node 22 or 24:
+
+```sh
+git clone https://github.com/DeployAnyway/doggo-log.git
+cd doggo-log
+git checkout feature/initial-mvp
+npm ci
+node examples/basic.js
+```
+
+After an approved release: `npm install @deployanyway/doggo-log`.
+
+## Quick start
+
+```js
+import { doglog, createDogLogger } from "@deployanyway/doggo-log";
+
+doglog.info("Server started");
+doglog.success("Tests passed");
+doglog.warn("API is getting slow");
+doglog.error("Database connection failed");
+
+const logger = createDogLogger({
+  timestamp: true,
+  level: "debug",
+  prefix: "app",
+});
+logger.debug("Listening on port %d", 3000);
+```
+
+## CLI example
+
+```sh
+node bin/cli.js success "Tests passed" --no-emoji
+node bin/cli.js info "Server started" --json --timestamp
+```
+
+After publication: `npx @deployanyway/doggo-log info "Server started"`.
+
+## API
+
+`doglog` is the default logger. `createDogLogger(options = {})` makes an independent
+logger. Both expose `log`, `info`, `success`, `warn`, `error`, and `debug`.
+Methods accept the same message arguments as Node's `util.format`, including
+format placeholders, objects, and Error instances. Zero arguments log the label
+alone. Each method returns its emitted string, or undefined if filtered/quiet.
+
+Default output sends warn/error to stderr and other methods to stdout. Logging
+an error does not set an exit code. The library never calls process.exit.
+Errors from a custom output function propagate to the caller.
+
+## Options
+
+| Option      | Default        | Behavior                                               |
+| ----------- | -------------- | ------------------------------------------------------ |
+| `emoji`     | true           | Dog-themed level symbols                               |
+| `color`     | false          | ANSI color for text lines; ignored for JSON            |
+| `timestamp` | false          | UTC ISO timestamp                                      |
+| `json`      | false          | One JSON object per call; emoji/color omitted          |
+| `quiet`     | false          | Suppress all output                                    |
+| `prefix`    | empty string   | Text prefix or JSON prefix field                       |
+| `level`     | info           | Minimum level                                          |
+| `write`     | console output | Function `(line, level)` for each emitted line         |
+| `clock`     | current Date   | Function returning a valid Date when timestamp enabled |
+
+Levels: debug (10), log/info/success (20), warn (30), error (40). Thresholds
+include all levels with equal or higher ranks. At info, debug is suppressed.
+At warn, only warn and error appear. JSON always includes `level` and `message`,
+with `prefix` and `timestamp` included when enabled/nonempty. Object arguments
+are formatted into the message string; they are not separate JSON fields.
+
+Invalid options throw TypeError; unknown levels throw RangeError. Names are case
+sensitive. Unknown option keys are ignored. Quiet/filtered calls skip message
+formatting, clock calls, and output. No transports, rotation, telemetry, remote
+service, or production dependencies are required.
+
+## CLI reference
+
+`doggo-log <method> <message> [options]`
+
+| Flag              | Behavior                          |
+| ----------------- | --------------------------------- |
+| `--json`          | JSON output                       |
+| `--timestamp`     | ISO timestamp                     |
+| `--no-emoji`      | Plain labels                      |
+| `--color`         | ANSI color                        |
+| `--prefix text`   | Prefix                            |
+| `--level name`    | Minimum level (CLI default debug) |
+| `--quiet`         | Suppress output                   |
+| `--help`, `-h`    | Usage                             |
+| `--version`, `-v` | Version                           |
+
+Quote messages containing shell punctuation. Use `--` before positional arguments
+containing dash-prefixed text. CLI messages are strings, without placeholder
+interpolation. Exit 0 means success (including filtered calls and error logging);
+exit 2 means invalid arguments. No stdin support in this MVP.
+
+## Development and examples
+
+```sh
+npm ci
+node examples/basic.js
+npm test
+npm run lint
+npm run format:check
+npm pack --dry-run
+```
+
+ES modules and Node's test runner. CI runs Node 22/24. Development tooling requires
+Node 22.13+ or 24. Styles and behavior are separate for easy contributions.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE).
+
+## More from DeployAnyway
+
+**Tools for developers who probably know better.**
+
+- [error-translator](https://github.com/DeployAnyway/error-translator)
+- [excuse-js](https://github.com/DeployAnyway/excuse-js)
+- [doggo-log](https://github.com/DeployAnyway/doggo-log)
+- [ship-it-meter](https://github.com/DeployAnyway/ship-it-meter)
+- [bro-say](https://github.com/DeployAnyway/bro-say)

package/bin/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { URL } from "node:url";
+import { createDogLogger } from "../src/index.js";
+import { levels } from "../src/levels.js";
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      json: { type: "boolean" },
+      timestamp: { type: "boolean" },
+      quiet: { type: "boolean" },
+      color: { type: "boolean" },
+      "no-emoji": { type: "boolean" },
+      prefix: { type: "string" },
+      level: { type: "string", default: "debug" },
+    },
+  });
+  if (values.help) {
+    console.log(
+      "Usage: doggo-log <method> <message> [options]\n\nMethods: log, info, success, warn, error, debug\nOptions:\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(
+      JSON.parse(
+        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+      ).version,
+    );
+  } else {
+    const [method, ...message] = positionals;
+    if (!Object.hasOwn(levels, method ?? "") || !message.join(" ").trim())
+      throw new TypeError("Provide a valid method and nonempty message.");
+    const logger = createDogLogger({
+      emoji: !values["no-emoji"],
+      color: values.color ?? false,
+      timestamp: values.timestamp ?? false,
+      json: values.json ?? false,
+      quiet: values.quiet ?? false,
+      prefix: values.prefix ?? "",
+      level: values.level,
+    });
+    logger[method](message.join(" "));
+  }
+} catch (error) {
+  console.error(`doggo-log: ${error.message}\nRun with --help for usage.`);
+  process.exitCode = 2;
+}

package/package.json

@@ -1,6 +1,41 @@
-{
-  "name": "@deployanyway/doggo-log",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@deployanyway/doggo-log",
+  "version": "0.1.0",
+  "description": "A tiny dog-themed logger with useful output and good manners.",
+  "type": "module",
+  "exports": "./src/index.js",
+  "bin": {
+    "doggo-log": "./bin/cli.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DeployAnyway/doggo-log.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DeployAnyway/doggo-log/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "eslint": "^10.12.0",
+    "prettier": "^3.6.2"
+  }
+}

package/src/index.js

@@ -0,0 +1,80 @@
+import { format } from "node:util";
+import { levels } from "./levels.js";
+
+/**
+ * Create a small logger. Methods return the emitted line, or undefined if filtered.
+ * @param {{emoji?: boolean, color?: boolean, timestamp?: boolean, json?: boolean, quiet?: boolean, prefix?: string, level?: string, write?: (line: string, level: string) => void, clock?: () => Date}} [options]
+ */
+export function createDogLogger(options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Options must be an object.");
+  const config = {
+    emoji: true,
+    color: false,
+    timestamp: false,
+    json: false,
+    quiet: false,
+    prefix: "",
+    level: "info",
+    write: (line, level) =>
+      level === "warn" || level === "error"
+        ? console.error(line)
+        : console.log(line),
+    clock: () => new Date(),
+    ...options,
+  };
+  for (const key of ["emoji", "color", "timestamp", "json", "quiet"]) {
+    if (typeof config[key] !== "boolean")
+      throw new TypeError(`${key} must be a boolean.`);
+  }
+  if (typeof config.prefix !== "string")
+    throw new TypeError("prefix must be a string.");
+  if (typeof config.level !== "string" || !Object.hasOwn(levels, config.level))
+    throw new RangeError(
+      `level must be one of: ${Object.keys(levels).join(", ")}.`,
+    );
+  if (typeof config.write !== "function" || typeof config.clock !== "function")
+    throw new TypeError("write and clock must be functions.");
+  return Object.fromEntries(
+    Object.entries(levels).map(([level, style]) => [
+      level,
+      (...args) => {
+        if (config.quiet || style.rank < levels[config.level].rank)
+          return undefined;
+        const message = format(...args);
+        let timestamp;
+        if (config.timestamp) {
+          const date = config.clock();
+          if (!(date instanceof Date) || !Number.isFinite(date.getTime()))
+            throw new TypeError("clock must return a valid Date.");
+          timestamp = date.toISOString();
+        }
+        let line;
+        if (config.json) {
+          line = JSON.stringify({
+            level,
+            message,
+            ...(config.prefix ? { prefix: config.prefix } : {}),
+            ...(timestamp ? { timestamp } : {}),
+          });
+        } else {
+          line = [
+            timestamp,
+            config.prefix,
+            config.emoji ? style.emoji : undefined,
+            level.toUpperCase().padEnd(7),
+            message,
+          ]
+            .filter((part) => part !== undefined && part !== "")
+            .join(" ");
+          if (config.color) line = `\u001b[${style.color}m${line}\u001b[0m`;
+        }
+        config.write(line, level);
+        return line;
+      },
+    ]),
+  );
+}
+
+/** Default logger: emoji enabled, no timestamp/color, info threshold. */
+export const doglog = createDogLogger();

package/src/levels.js

@@ -0,0 +1,8 @@
+export const levels = {
+  debug: { rank: 10, emoji: "🔍", color: 90 },
+  log: { rank: 20, emoji: "🐶", color: 37 },
+  info: { rank: 20, emoji: "🐶", color: 36 },
+  success: { rank: 20, emoji: "🐾", color: 32 },
+  warn: { rank: 30, emoji: "🦴", color: 33 },
+  error: { rank: 40, emoji: "🚨", color: 31 },
+};