@portosaur/logger 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @portosaur/logger
+
+> **The missing Docusaurus-style logger.** A lightweight, Docusaurus-compatible logging library enhanced with semantic levels, flexible alignment, and elegant box rendering.
+
+Designed to provide the familiar Docusaurus terminal experience to any CLI project, while adding essential utilities like `consola`-powered boxes and custom `tip`/`note` levels.
+
+## Install
+
+```bash
+bun add @portosaur/logger
+
+# or
+npm install @portosaur/logger
+```
+
+## Usage
+
+```js
+import logger, { colors } from "@portosaur/logger";
+
+// Inline log
+logger.info("Starting setup...");
+logger.success("Build complete!");
+logger.warn("Dependency outdated");
+logger.error("Build failed");
+logger.tip("Run dev to preview");
+logger.note("Remember to commit");
+
+// Debug — only shown when DEBUG=1 or VERBOSE=1
+logger.debug("Resolved config: /home/user/config.yml");
+
+// Box — color pre-applied per level, CI-safe
+logger.success.box("Build complete!", { title: "Result" });
+logger.warn.box("Outdated dependency found", { title: "Warning" });
+logger.note.box("Project initialized", { title: "Next Steps" });
+
+// Start — helper that resets view and logs info
+logger.start("Bootstrapping project...");
+
+// Semantic colors
+console.log(colors.command("porto dev"));
+console.log(colors.url("https://example.com"));
+console.log(colors.muted("(optional)"));
+```
+
+## Log Levels
+
+Every level is a `LevelFn`:
+
+```typescript
+interface LevelFn {
+  (msg: string): void;
+  box(msg: string, options?: BoxOptions): void;
+}
+
+interface BoxOptions {
+  title?: string;
+  padding?: number;
+  border?: "rounded" | "single" | "double" | "none";
+}
+```
+
+| Level     | Label       | Notes                                    |
+| :-------- | :---------- | :--------------------------------------- |
+| `info`    | `[INFO]`    | Standard informational message           |
+| `success` | `[SUCCESS]` | Operation completed successfully         |
+| `warn`    | `[WARNING]` | Non-fatal warning                        |
+| `error`   | `[ERROR]`   | Error message                            |
+| `debug`   | `[INFO]`    | Only shown when `DEBUG=1` or `VERBOSE=1` |
+| `tip`     | `[TIP]`     | Magenta colored label                    |
+| `note`    | `[NOTE]`    | Gray colored label                       |
+
+## Utilities
+
+- **`logger.start(msg)`**: A specialized helper that calls `logger.resetView()` and then `logger.info(msg)`. Ideal for initiating a new process.
+- **`logger.resetView()`**: Clears the console and resets cursor position.
+- **`logger.clear()`**: A standard console clear (no-op in test environments).
+
+`.box()` on any level automatically degrades to an inline log when `CI=true`.
+
+## Colors
+
+```js
+import { colors } from "@portosaur/logger";
+
+colors.bold("text");
+colors.command("porto dev"); // cyan bold — shell commands
+colors.url("https://..."); // cyan underline
+colors.muted("(optional)"); // gray — hints
+colors.heading("Result"); // yellow — titles
+colors.label("Name"); // white bold — field labels
+```
+
+Standard chalk colors (`red`, `green`, `blue`, etc.) and modifiers (`bold`, `dim`, `italic`, etc.) are also available.
+
+## License
+
+GPL-3.0-only

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@portosaur/logger",
+  "version": "0.1.0",
+  "description": "Portosaur Logger: CLI output utilities and level normalization.",
+  "author": "soymadip",
+  "license": "GPL-3.0-only",
+  "homepage": "https://soymadip.github.io/portosaur",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/soymadip/portosaur"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs",
+      "default": "./src/index.mjs"
+    }
+  },
+  "types": "./src/index.d.ts",
+  "dependencies": {
+    "@docusaurus/logger": "^3.10.0",
+    "chalk": "^5.6.2",
+    "consola": "^3.4.2"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Functional color utility (Chalk-like).
+ */
+export type ColorFn = (str: string | number) => string;
+
+export interface Colors {
+  // Modifiers
+  bold: ColorFn;
+  dim: ColorFn;
+  italic: ColorFn;
+  underline: ColorFn;
+  strikethrough: ColorFn;
+  inverse: ColorFn;
+  reset: ColorFn;
+
+  // Foreground Colors
+  black: ColorFn;
+  red: ColorFn;
+  green: ColorFn;
+  yellow: ColorFn;
+  blue: ColorFn;
+  magenta: ColorFn;
+  cyan: ColorFn;
+  white: ColorFn;
+  gray: ColorFn;
+  grey: ColorFn;
+
+  // Bright Colors
+  blackBright: ColorFn;
+  redBright: ColorFn;
+  greenBright: ColorFn;
+  yellowBright: ColorFn;
+  blueBright: ColorFn;
+  magentaBright: ColorFn;
+  cyanBright: ColorFn;
+  whiteBright: ColorFn;
+
+  // Background Colors
+  bgBlack: ColorFn;
+  bgRed: ColorFn;
+  bgGreen: ColorFn;
+  bgYellow: ColorFn;
+  bgBlue: ColorFn;
+  bgMagenta: ColorFn;
+  bgCyan: ColorFn;
+  bgWhite: ColorFn;
+
+  // Semantic Wrappers
+  muted: ColorFn;
+  success: ColorFn;
+  warn: ColorFn;
+  error: ColorFn;
+  info: ColorFn;
+  tip: ColorFn;
+  heading: ColorFn;
+  command: ColorFn;
+  label: ColorFn;
+  url: ColorFn;
+}
+
+export interface BoxOptions {
+  /** The title of the box. */
+  title?: string;
+
+  /** The padding inside the box. Default is 1. */
+  padding?: number;
+
+  /** The border style. Default is "rounded". */
+  border?: "rounded" | "single" | "double" | "none";
+}
+
+export interface LevelFn {
+  /** Log a message at this level. */
+  (msg: string): void;
+
+  /** Display a styled box using this level's semantic color. */
+  box(msg: string, options?: BoxOptions): void;
+}
+
+export interface Logger {
+  // Standard levels — routed through @docusaurus/logger
+  info: LevelFn;
+  success: LevelFn;
+  warn: LevelFn;
+  error: LevelFn;
+
+  // Gated — only logs when DEBUG or VERBOSE env var is set
+  debug: LevelFn;
+
+  // Custom levels — console.log with aligned colored label
+  tip: LevelFn;
+  note: LevelFn;
+
+  // Utilities
+
+  /** Logs a blank line. */
+  newLine(): void;
+
+  /** Logs a blank line followed by an info message. */
+  start(msg: string): void;
+  clear(): void;
+  resetView(): void;
+
+  /** Async wait/sleep for a specified number of milliseconds. */
+  wait(ms: number, options?: { ci?: boolean; test?: boolean }): Promise<void>;
+}
+
+/**
+ * Portosaur Logger
+ * Wraps @docusaurus/logger and consola with additional helpers.
+ */
+export const logger: Logger;
+export default logger;
+
+/**
+ * Semantic color utilities (chalk wrapper).
+ */
+export const colors: Colors;

package/src/index.mjs

@@ -0,0 +1,73 @@
+import { colors } from "./lib/colors.mjs";
+import { createLevel, createCustomLevel } from "./lib/helpers.mjs";
+
+/*
+ * Portosaur Logger
+ * Wraps @docusaurus/logger and consola with additional helpers.
+ */
+export const logger = {
+  // Standard levels — routed through @docusaurus/logger
+  info: createLevel("info"),
+  success: createLevel("success"),
+  warn: createLevel("warn"),
+  error: createLevel("error"),
+
+  // Gated — only logs when DEBUG or VERBOSE env var is set
+  debug: createLevel("debug", { gated: true }),
+
+  // Custom levels — console.log with aligned colored label
+  tip: createCustomLevel("tip", colors.tip),
+  note: createCustomLevel("note", colors.muted),
+
+  //--------------- Utilities --------------------------
+
+  /** Prints a visually empty line (using a zero-width space) to avoid console pruning. */
+  newLine: () => {
+    console.log("\u200B");
+  },
+
+  /** Prints a newline followed by an info message. */
+  start: (msg) => {
+    logger.newLine();
+    logger.info(msg);
+  },
+
+  /** Clears the terminal screen (skipped in test environment). */
+  clear: () => {
+    if (process.env.NODE_ENV !== "test") {
+      process.stdout.write("\x1bc");
+    }
+  },
+
+  /** Resets the terminal view/scrollback (skipped in test environment). */
+  resetView: () => {
+    if (process.env.NODE_ENV !== "test") {
+      process.stdout.write("\x1B[2J\x1B[H");
+    }
+  },
+
+  /**
+   * Asynchronous wait (sleep) utility that is environment-aware.
+   * @param {number} ms - Milliseconds to wait.
+   * @param {Object} [options] - Skip options.
+   * @param {boolean} [options.ci=false] - If true, do not skip in CI.
+   * @param {boolean} [options.test=false] - If true, do not skip in test.
+   * @returns {Promise<void>}
+   */
+  wait: (ms, { ci = false, test = false } = {}) => {
+    const isTest = process.env.NODE_ENV === "test";
+    const isCI = !!process.env.CI;
+
+    if ((isTest && !test) || (isCI && !ci)) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  },
+};
+
+/*
+ * ======================= Export the logger & Helpers ===============================
+ */
+
+export default logger;
+export { colors };

package/src/lib/colors.mjs

@@ -0,0 +1,65 @@
+import chalk from "chalk";
+
+/**
+ * Portosaur Color Palette
+ *
+ * A full-featured semantic wrapper over chalk.
+ * To swap the underlying library, only this file needs to change.
+ */
+export const colors = {
+  // ------- Text Modifiers -------
+  // Modifiers
+  bold: (str) => chalk.bold(str),
+  dim: (str) => chalk.dim(str),
+  italic: (str) => chalk.italic(str),
+  underline: (str) => chalk.underline(str),
+  strikethrough: (str) => chalk.strikethrough(str),
+  inverse: (str) => chalk.inverse(str),
+  reset: (str) => chalk.reset(str),
+
+  // Foreground Colors
+  black: (str) => chalk.black(str),
+  red: (str) => chalk.red(str),
+  green: (str) => chalk.green(str),
+  yellow: (str) => chalk.yellow(str),
+  blue: (str) => chalk.blue(str),
+  magenta: (str) => chalk.magenta(str),
+  cyan: (str) => chalk.cyan(str),
+  white: (str) => chalk.white(str),
+  gray: (str) => chalk.gray(str),
+  grey: (str) => chalk.grey(str),
+
+  // Bright Colors
+  blackBright: (str) => chalk.blackBright(str),
+  redBright: (str) => chalk.redBright(str),
+  greenBright: (str) => chalk.greenBright(str),
+  yellowBright: (str) => chalk.yellowBright(str),
+  blueBright: (str) => chalk.blueBright(str),
+  magentaBright: (str) => chalk.magentaBright(str),
+  cyanBright: (str) => chalk.cyanBright(str),
+  whiteBright: (str) => chalk.whiteBright(str),
+
+  // Background Colors
+  bgBlack: (str) => chalk.bgBlack(str),
+  bgRed: (str) => chalk.bgRed(str),
+  bgGreen: (str) => chalk.bgGreen(str),
+  bgYellow: (str) => chalk.bgYellow(str),
+  bgBlue: (str) => chalk.bgBlue(str),
+  bgMagenta: (str) => chalk.bgMagenta(str),
+  bgCyan: (str) => chalk.bgCyan(str),
+  bgWhite: (str) => chalk.bgWhite(str),
+
+  // Semantic Wrappers
+  muted: (str) => chalk.gray(str), // subdued hints, placeholders
+  success: (str) => chalk.green(str), // success messages
+  warn: (str) => chalk.yellow(str), // warnings, back-nav
+  error: (str) => chalk.red(str), // errors
+  info: (str) => chalk.blue(str), // informational text
+  tip: (str) => chalk.magenta.bold(str), // [TIP] prefix
+  heading: (str) => chalk.yellow(str), // note/box headings
+  command: (str) => chalk.cyan.bold(str), // shell commands / code
+  label: (str) => chalk.white.bold(str), // field labels
+  url: (str) => chalk.cyanBright.underline(str), // clickable URLs
+};
+
+export default colors;

package/src/lib/helpers.mjs

@@ -0,0 +1,153 @@
+import dLogger from "@docusaurus/logger";
+import { consola } from "consola";
+import { colors } from "./colors.mjs";
+
+// ================= Message Formatting ====================
+
+export const TARGET_WIDTH = 10;
+
+/**
+ * Format messages for Docusaurus logger with a fixed label column.
+ *
+ * @param {string} rawMsg     - The message to log.
+ * @param {string} levelLabel - The level (info, success, etc).
+ * @returns {string} The formatted message.
+ */
+export function _formatMsg(rawMsg, levelLabel) {
+  // Parse input message
+  const s = rawMsg === undefined || rawMsg === null ? "" : String(rawMsg);
+  const leading = s.match(/^\n+/)?.[0] || "";
+  const body = s.replace(/^\n+/, "");
+
+  // Return early if empty
+  if (body === "") {
+    return leading;
+  }
+
+  // Prepare label and calculate padding
+  const LABEL_MAP = {
+    warn: "WARNING",
+  };
+
+  const labelText = `[${(LABEL_MAP[levelLabel] || levelLabel).toUpperCase()}]`;
+  const lines = body.split(/\r?\n/);
+
+  // Format each line with proper indentation
+  const formatted = lines.map((ln, idx) => {
+    if (idx === 0) {
+      const padding = TARGET_WIDTH - (labelText.length + 1);
+      return " ".repeat(Math.max(0, padding)) + ln;
+    }
+    return " ".repeat(TARGET_WIDTH) + ln;
+  });
+
+  // Return formatted output
+  return leading + formatted.join("\n");
+}
+
+// ================= Routing & Logging ====================
+
+// Levels with a native method in @docusaurus/logger
+const DOCUSAURUS_LEVELS = new Set(["info", "success", "warn", "error"]);
+
+export const IS_CI = !!process.env.CI;
+
+function dlog(msg, level) {
+  const s = msg === undefined || msg === null ? "" : String(msg);
+  const leading = s.match(/^\n+/)?.[0] || "";
+  const body = s.replace(/^\n+/, "");
+
+  // Write leading newlines
+  if (leading) {
+    process.stdout.write(leading);
+  }
+
+  // Format and route the message
+  const formatted = _formatMsg(body, level);
+  const dl = dLogger.default || dLogger;
+  const method = DOCUSAURUS_LEVELS.has(level) ? level : "info";
+  return dl[method](formatted);
+}
+
+// ================= Box Helper ====================
+
+const LEVEL_BOX_COLORS = {
+  info: "blue",
+  success: "green",
+  warn: "yellow",
+  error: "red",
+  start: "blue",
+  debug: "gray",
+  tip: "magenta",
+  note: "gray",
+};
+
+function makeBox(level, inlineFn) {
+  const boxColor = LEVEL_BOX_COLORS[level] ?? "cyan";
+  return function box(msg, options = {}) {
+    const {
+      title = level.toUpperCase(),
+      padding = 1,
+      border = "rounded",
+    } = options;
+
+    if (IS_CI) {
+      // Fallback to plain log — boxes don't render well in raw CI logs
+      inlineFn(title ? `${title}: ${msg}` : msg);
+      return;
+    }
+    consola.box({
+      message: ` ${msg} `,
+      title: title ? colors.heading(` ${title} `) : "",
+      style: {
+        borderColor: boxColor,
+        borderStyle: border,
+        padding: padding,
+      },
+    });
+  };
+}
+
+// ================= Level Factories ====================
+
+/**
+ * Standard level — routed through @docusaurus/logger.
+ * @param {string} level
+ * @param {{ gated?: boolean }} options - gated: only log when DEBUG/VERBOSE is set
+ */
+export function createLevel(level, { gated = false } = {}) {
+  const fn = (msg) => {
+    if (gated && !process.env.DEBUG && !process.env.VERBOSE) {
+      return;
+    }
+    dlog(msg, level);
+  };
+  fn.box = makeBox(level, fn);
+  return fn;
+}
+
+/**
+ * Custom level — uses console.log + _formatMsg with its own colored label.
+ * Does NOT route through @docusaurus/logger.
+ * @param {string} level
+ * @param {Function} colorFn - chalk color function for the label
+ */
+export function createCustomLevel(level, colorFn) {
+  const label = `[${level.toUpperCase()}]`;
+  const fn = (msg) => {
+    // Parse input message
+    const s = msg === undefined || msg === null ? "" : String(msg);
+    const leading = s.match(/^\n+/)?.[0] || "";
+    const body = s.replace(/^\n+/, "");
+
+    // Write leading newlines
+    if (leading) {
+      process.stdout.write(leading);
+    }
+
+    // Format and output
+    console.log(`${colorFn(label)} ${_formatMsg(body, level)}`);
+  };
+  fn.box = makeBox(level, fn);
+  return fn;
+}

package/tests/logger.format.test.mjs

@@ -0,0 +1,43 @@
+import { expect, test, describe } from "bun:test";
+import { _formatMsg, TARGET_WIDTH } from "../src/lib/helpers.mjs";
+
+const stripAnsi = (s) => (s || "").replace(/\x1b\[[0-9;]*m/g, "");
+
+describe("logger formatting", () => {
+  test("single-line message aligns", () => {
+    const levelLabel = "success";
+    const labelText = `[${levelLabel.toUpperCase()}]`;
+    const currentLabelLength = labelText.length + 1;
+    const paddingCount = TARGET_WIDTH - currentLabelLength;
+    const out = _formatMsg("Installation complete", levelLabel);
+    const raw = stripAnsi(out);
+    expect(raw).toBe(" ".repeat(paddingCount) + "Installation complete");
+  });
+
+  test("leading newline preserved", () => {
+    const levelLabel = "error";
+    const labelText = `[${levelLabel.toUpperCase()}]`;
+    const currentLabelLength = labelText.length + 1;
+    const paddingCount = TARGET_WIDTH - currentLabelLength;
+    const out = _formatMsg("\nSetup aborted.", levelLabel);
+    const raw = stripAnsi(out);
+    expect(raw).toBe("\n" + " ".repeat(paddingCount) + "Setup aborted.");
+  });
+
+  test("multi-line message indents subsequent lines", () => {
+    const levelLabel = "info";
+    const labelText = `[${levelLabel.toUpperCase()}]`;
+    const currentLabelLength = labelText.length + 1;
+    const paddingCount = TARGET_WIDTH - currentLabelLength;
+    const out = _formatMsg("Line1\nLine2\nLine3", levelLabel);
+    const raw = stripAnsi(out);
+    const expected =
+      " ".repeat(paddingCount) +
+      "Line1\n" +
+      " ".repeat(TARGET_WIDTH) +
+      "Line2\n" +
+      " ".repeat(TARGET_WIDTH) +
+      "Line3";
+    expect(raw).toBe(expected);
+  });
+});