@enke.dev/logbox 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 enke.dev
+
+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

@@ -0,0 +1,140 @@
+# logbox
+
+Wraps a long-running command and pins a configurable info box to the bottom of the terminal. The
+wrapped command's output scrolls above it, unaltered — colors, spinners and all.
+
+```
+[dev:docs] vite v7.1.0 ready in 431 ms
+[dev:components] build started…
+╭─ dev servers ──────────────────────────────────────────────────────────────╮
+│ docs..............................................https://localhost:5173  │
+│ components (web)..................................https://localhost:5174  │
+│ components (react)................................https://localhost:5175  │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+## tl;dr
+
+```sh
+# as a dev dependency
+npm i -D @enke.dev/logbox
+# or globally
+npm i -g @enke.dev/logbox
+
+# wrap whatever you already run
+logbox pnpm -r --parallel --stream dev
+```
+
+Or without installing:
+
+```sh
+npx @enke.dev/logbox pnpm -r --parallel --stream dev
+pnpm dlx @enke.dev/logbox pnpm -r --parallel --stream dev
+bunx --bun @enke.dev/logbox pnpm -r --parallel --stream dev
+```
+
+Typical use is a `package.json` script:
+
+```json
+{
+  "scripts": {
+    "dev": "logbox pnpm -r --parallel --stream dev:*"
+  }
+}
+```
+
+## How it works
+
+The box lives in terminal lines that are reserved by shrinking the scroll region, so it is not part
+of the output stream: nothing scrolls it away, and nothing is rewritten or filtered on the way
+through. Redraws are coalesced, so a burst of output costs one render.
+
+Without a TTY (pipes, CI logs) there is nothing to pin the box to, so the content is printed once up
+front as a flat list and the child inherits stdio directly.
+
+Signals (`SIGINT`, `SIGTERM`, `SIGHUP`) are handed down to the child, which decides when to go away.
+logbox exits with the child's exit code, so it stays transparent in scripts.
+
+## Configuration
+
+Content is an **array of rows**; each row is an **array of strings**:
+
+- the first cell is left aligned,
+- the last cell is right aligned,
+- a dot leader connects them,
+- middle cells (3+ per row) get their own aligned column,
+- a row with a single cell renders as a plain label.
+
+### `.logbox.json`
+
+Looked up in the current directory, then every parent up to the filesystem root — so a file in the
+repo root is found from any nested cwd — and finally in the user home directory (`~/.logbox.json`)
+as a global fallback. The nearest file wins.
+
+Bare rows:
+
+```json
+[
+  ["docs", "https://localhost:5173"],
+  ["components", "https://localhost:5174"]
+]
+```
+
+Or the object form, which adds a title:
+
+```json
+{
+  "$schema": "https://enke-dev.github.io/logbox/logbox.schema.json",
+  "title": "dev servers",
+  "content": [
+    ["docs", "https://localhost:5173"],
+    ["components", "https://localhost:5174"]
+  ]
+}
+```
+
+The JSON schema is published with every release at
+**<https://enke-dev.github.io/logbox/logbox.schema.json>** — reference it via `$schema` for editor
+completion and validation.
+
+### Inline
+
+`--content` takes the same JSON and skips the file lookup entirely:
+
+```sh
+logbox -c '[["docs","https://localhost:5173"]]' -t 'dev servers' npm run dev
+```
+
+## Options
+
+Only the options ahead of the wrapped command belong to logbox — everything from the first non-flag
+token on is passed through verbatim, so the wrapped command keeps its own flags
+(`logbox pnpm -r --parallel dev`). Use `--` if the command itself starts with a dash.
+
+| Option                 | Description                                               |
+| ---------------------- | --------------------------------------------------------- |
+| `-c, --content <json>` | Box content as inline JSON; overrides any config file     |
+| `-t, --title <text>`   | Title rendered into the top border (default: `logbox`)    |
+| `--config <path>`      | Read the content from this file instead of looking one up |
+| `-h, --help`           | Show help                                                 |
+| `-v, --version`        | Print the version                                         |
+
+With no content configured anywhere, logbox draws no box and simply runs the command.
+
+## Development
+
+```sh
+bun install
+bun run dev -c '[["a","b"]]' -- sleep 5   # run from source
+bun run check                             # types
+bun run lint                              # eslint + prettier
+bun run test                              # specs under bun and node
+bun run build                             # dist/cli.mjs
+```
+
+Releases are trunk based: pushing to `main` cuts the semver release from the conventional commits
+since the last tag and republishes the schema to GitHub Pages.
+
+## License
+
+MIT

package/dist/cli.mjs

@@ -0,0 +1,425 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import process3, { argv, stderr as stderr2, stdout as stdout2 } from "node:process";
+// package.json
+var package_default = {
+  name: "@enke.dev/logbox",
+  version: "0.0.1",
+  license: "MIT",
+  packageManager: "bun@1.3.14",
+  publishConfig: {
+    registry: "https://registry.npmjs.org",
+    access: "public"
+  },
+  description: "Wraps a long-running command and pins a configurable info box to the bottom of the terminal.",
+  keywords: [
+    "cli",
+    "terminal",
+    "tty",
+    "dev-server",
+    "box"
+  ],
+  author: {
+    name: "David Enke",
+    email: "david@enke.dev"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/enke-dev/logbox.git"
+  },
+  homepage: "https://enke-dev.github.io/logbox/",
+  type: "module",
+  bin: {
+    logbox: "./dist/cli.mjs"
+  },
+  files: [
+    "dist/cli.mjs"
+  ],
+  engines: {
+    node: ">=22"
+  },
+  scripts: {
+    prepare: "bun run build",
+    check: "tsgo --noEmit",
+    lint: "run-p lint:*",
+    "lint:eslint": "bun --bun eslint --config eslint.config.ts",
+    "lint:prettier": "bun --bun prettier --config prettier.config.ts --check .",
+    format: "run-p format:*",
+    "format:eslint": "bun --bun eslint --config eslint.config.ts --fix",
+    "format:prettier": "bun --bun prettier --config prettier.config.ts --write .",
+    test: "run-p -c test:*",
+    "test:bun": "bun test --reporter=junit --reporter-outfile=reports/junit.bun.xml",
+    "test:node": 'node --import tsx --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=reports/junit.node.xml "src/**/*.spec.ts"',
+    dev: "bun run --bun src/cli.ts",
+    build: "bun build ./src/cli.ts --target=node --outfile dist/cli.mjs"
+  },
+  devDependencies: {
+    "@enke.dev/lint": "0.13.8",
+    "@tsconfig/strictest": "2.0.8",
+    "@types/bun": "1.3.14",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    eslint: "10.8.1",
+    jiti: "2.7.0",
+    "npm-run-all2": "9.0.3",
+    prettier: "3.9.6",
+    tsx: "4.23.12",
+    typescript: "6.0.3"
+  }
+};
+
+// src/args/args.ts
+import { parseArgs } from "node:util";
+var OPTIONS = {
+  content: { type: "string", short: "c" },
+  title: { type: "string", short: "t" },
+  config: { type: "string" },
+  help: { type: "boolean", short: "h", default: false },
+  version: { type: "boolean", short: "v", default: false }
+};
+var VALUE_FLAGS = new Set(["-c", "--content", "-t", "--title", "--config"]);
+function split(argv) {
+  let index = 0;
+  while (index < argv.length) {
+    const token = argv[index];
+    if (token === "--") {
+      return { options: argv.slice(0, index), command: argv.slice(index + 1) };
+    }
+    if (!token.startsWith("-") || token === "-") {
+      break;
+    }
+    index += VALUE_FLAGS.has(token) ? 2 : 1;
+  }
+  return { options: argv.slice(0, index), command: argv.slice(index) };
+}
+function parseCommandLine(argv) {
+  const { options, command } = split(argv);
+  const { values } = parseArgs({ args: options, options: OPTIONS });
+  return { ...values, command };
+}
+
+// src/config/config.ts
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+var DEFAULT_TITLE = "logbox";
+var CONFIG_FILE = ".logbox.json";
+function emptyConfig() {
+  return { title: DEFAULT_TITLE, content: [], source: "none" };
+}
+function configCandidates(cwd, home) {
+  const climb = (directory, seen) => {
+    const parent = dirname(directory);
+    return parent === directory ? [...seen, directory] : climb(parent, [...seen, directory]);
+  };
+  const paths = climb(resolve(cwd), []).map((directory) => join(directory, CONFIG_FILE));
+  const global = join(home, CONFIG_FILE);
+  return paths.includes(global) ? paths : [...paths, global];
+}
+function toRows(value, source) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${source}: expected an array of rows, e.g. [["docs", "https://localhost"]]`);
+  }
+  return value.map((row, index) => {
+    if (!Array.isArray(row) || row.some((cell) => typeof cell !== "string")) {
+      throw new Error(`${source}: row ${index} must be an array of strings`);
+    }
+    if (row.length === 0) {
+      throw new Error(`${source}: row ${index} must hold at least one entry`);
+    }
+    return row;
+  });
+}
+function normalize(value, source) {
+  if (Array.isArray(value)) {
+    return { title: DEFAULT_TITLE, content: toRows(value, source), source };
+  }
+  if (typeof value !== "object" || value === null) {
+    throw new Error(`${source}: expected an array of rows or an object with a "content" array`);
+  }
+  const { title, content } = value;
+  if (title !== undefined && typeof title !== "string") {
+    throw new Error(`${source}: "title" must be a string`);
+  }
+  return { title: title ?? DEFAULT_TITLE, content: toRows(content, source), source };
+}
+function parse(raw, source) {
+  try {
+    return normalize(JSON.parse(raw), source);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`${source}: invalid JSON — ${error.message}`, { cause: error });
+    }
+    throw error;
+  }
+}
+async function readConfig(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return;
+  }
+  return parse(raw, path);
+}
+async function loadConfig(options = {}) {
+  const { content, title, config, cwd = process.cwd(), home = homedir() } = options;
+  const withTitle = (resolved) => title === undefined ? resolved : { ...resolved, title };
+  if (content !== undefined) {
+    return withTitle(parse(content, "--content"));
+  }
+  if (config !== undefined) {
+    const explicit = await readConfig(resolve(cwd, config));
+    if (explicit === undefined) {
+      throw new Error(`${config}: config file not found`);
+    }
+    return withTitle(explicit);
+  }
+  const candidates = configCandidates(cwd, home);
+  const found = await candidates.reduce(async (previous, path) => await previous ?? await readConfig(path), Promise.resolve(undefined));
+  return withTitle(found ?? emptyConfig());
+}
+
+// src/render/ansi.ts
+var ESC = "\x1B";
+var CSI = `${ESC}[`;
+var RESET = `${CSI}0m`;
+var RED = `${CSI}31m`;
+var DIM = `${CSI}2m`;
+var BOLD = `${CSI}1m`;
+var CYAN = `${CSI}36m`;
+var GREEN = `${CSI}32m`;
+var COLOR = {
+  border: `${CSI}38;5;39m`,
+  title: `${CSI}1;38;5;45m`,
+  head: `${CSI}38;5;250m`,
+  leader: `${CSI}38;5;240m`,
+  tail: `${CSI}4;38;5;79m`
+};
+var SAVE_CURSOR = `${ESC}7`;
+var RESTORE_CURSOR = `${ESC}8`;
+var CLEAR_LINE = `${CSI}2K`;
+var RESET_SCROLL_REGION = `${CSI}r`;
+function cursorTo(row, column = 1) {
+  return `${CSI}${row};${column}H`;
+}
+function setScrollRegion(top, bottom) {
+  return `${CSI}${top};${bottom}r`;
+}
+
+// src/help/help.ts
+var SCHEMA_URL = "https://enke-dev.github.io/logbox/logbox.schema.json";
+var SECTIONS = [
+  {
+    title: "Usage",
+    lines: ["logbox [options] <command> [...args]", "logbox [options] -- <command> [...args]"]
+  },
+  {
+    title: "Options",
+    lines: [
+      `${GREEN}-c, --content${RESET} <json>  Box content as inline JSON, e.g. '[["docs","https://localhost:5173"]]'`,
+      `${GREEN}-t, --title${RESET} <text>    Title rendered into the top border`,
+      `${GREEN}    --config${RESET} <path>   Read the content from this file instead of looking one up`,
+      `${GREEN}-h, --help${RESET}            Show this help`,
+      `${GREEN}-v, --version${RESET}         Print the version`
+    ]
+  },
+  {
+    title: "Content",
+    lines: [
+      "An array of rows; each row is an array of strings. The first cell is left",
+      "aligned, the last one right aligned, connected by a dot leader. A row with a",
+      "single cell renders as a plain label.",
+      "",
+      'Either bare rows or an object: {"title": "dev servers", "content": [[...]]}',
+      `Schema: ${SCHEMA_URL}`
+    ]
+  },
+  {
+    title: "Configuration",
+    lines: [
+      `${CONFIG_FILE} is looked up in the current directory, then every parent up to`,
+      "the filesystem root (so the repo root is found from anywhere), then the user",
+      "home directory. --content overrides the file, --title overrides its title."
+    ]
+  },
+  {
+    title: "Examples",
+    lines: [
+      "logbox pnpm -r --parallel --stream dev",
+      `logbox -c '[["docs","https://localhost:5173"]]' -t 'dev servers' npm run dev`
+    ]
+  }
+];
+function helpText() {
+  const header = `${BOLD}logbox${RESET} — pin a configurable box below a long-running command`;
+  const sections = SECTIONS.map(({ title, lines }) => `${BOLD}${CYAN}${title}${RESET}
+${lines.map((line) => line === "" ? line : `  ${line}`).join(`
+`)}`);
+  return `${[header, ...sections].join(`
+
+`)}
+`;
+}
+
+// src/run/run.ts
+import { spawn } from "node:child_process";
+import process2, { env, platform, stderr, stdout } from "node:process";
+
+// src/render/box.ts
+var GLYPH = {
+  topLeft: "╭",
+  topRight: "╮",
+  bottomLeft: "╰",
+  bottomRight: "╯",
+  horizontal: "─",
+  vertical: "│",
+  leader: "."
+};
+var MIN_INNER = 8;
+function boxHeight(rows) {
+  return rows.length + 2;
+}
+function truncate(value, width) {
+  if (value.length <= width) {
+    return value;
+  }
+  return width > 0 ? `${value.slice(0, width - 1)}…` : "";
+}
+function headWidths(rows) {
+  return rows.reduce((widths, row) => {
+    row.slice(0, -1).forEach((cell, index) => {
+      widths[index] = Math.max(widths[index] ?? 0, cell.length);
+    });
+    return widths;
+  }, []);
+}
+function rowParts(row, widths, body) {
+  const cells = row.length > 1 ? row : [...row, ""];
+  const heads = cells.slice(0, -1);
+  const last = heads.length - 1;
+  const head = truncate(heads.map((cell, index) => index < last ? cell.padEnd(widths[index] ?? cell.length) : cell).join(" "), Math.max(0, body - 2));
+  const tail = truncate(cells.at(-1) ?? "", Math.max(0, body - head.length - 1));
+  const fill = Math.max(0, body - head.length - tail.length);
+  return tail === "" ? { head, leader: "", tail, pad: " ".repeat(fill) } : { head, leader: GLYPH.leader.repeat(fill), tail, pad: "" };
+}
+function renderBox({ title, rows, columns }) {
+  const inner = Math.max(MIN_INNER, title.length + 4, columns - 2);
+  const body = inner - 2;
+  const widths = headWidths(rows);
+  const heading = `${COLOR.title}${title}${COLOR.border}`;
+  const top = `${GLYPH.topLeft}${GLYPH.horizontal} ${heading} ` + `${GLYPH.horizontal.repeat(Math.max(0, inner - title.length - 3))}${GLYPH.topRight}`;
+  const bottom = `${GLYPH.bottomLeft}${GLYPH.horizontal.repeat(inner)}${GLYPH.bottomRight}`;
+  const lines = rows.map((row) => {
+    const { head, leader, tail, pad } = rowParts(row, widths, body);
+    return `${COLOR.border}${GLYPH.vertical}${RESET} ` + `${COLOR.head}${head}${RESET}` + `${COLOR.leader}${leader}${RESET}` + `${COLOR.tail}${tail}${RESET}${pad} ` + `${COLOR.border}${GLYPH.vertical}${RESET}`;
+  });
+  return [`${COLOR.border}${top}${RESET}`, ...lines, `${COLOR.border}${bottom}${RESET}`];
+}
+function renderPlain({ title, rows }) {
+  const widths = headWidths(rows);
+  const lines = rows.map((row) => row.length === 1 ? row[0] ?? "" : row.slice(0, -1).map((cell, index) => cell.padEnd(widths[index] ?? cell.length)).concat([row.at(-1) ?? ""]).join("  "));
+  return [`${title}:`, ...lines];
+}
+
+// src/run/run.ts
+var REDRAW_DELAY = 8;
+var size = () => ({
+  rows: stdout.rows || 24,
+  columns: stdout.columns || 80
+});
+function runWithBox(command, config) {
+  const [bin, ...args] = command;
+  const { title, content: rows } = config;
+  const height = boxHeight(rows);
+  const sticky = rows.length > 0 && stdout.isTTY === true;
+  if (rows.length > 0 && !sticky) {
+    stdout.write(`${renderPlain({ title, rows }).join(`
+`)}
+`);
+  }
+  const scrollBottom = () => Math.max(1, size().rows - height);
+  const drawBox = () => {
+    const lines = renderBox({ title, rows, columns: size().columns });
+    const top = Math.max(1, size().rows - lines.length + 1);
+    const box = lines.map((line, index) => `${cursorTo(top + index)}${CLEAR_LINE}${line}`).join("");
+    stdout.write(`${SAVE_CURSOR}${box}${RESTORE_CURSOR}`);
+  };
+  let scheduled;
+  const scheduleBox = () => {
+    clearTimeout(scheduled);
+    scheduled = setTimeout(drawBox, REDRAW_DELAY);
+    scheduled.unref?.();
+  };
+  const child = spawn(bin, args, {
+    env: { ...env, FORCE_COLOR: env["FORCE_COLOR"] ?? "1" },
+    shell: platform === "win32",
+    stdio: sticky ? ["inherit", "pipe", "pipe"] : "inherit"
+  });
+  if (sticky) {
+    stdout.write(`
+`.repeat(height));
+    stdout.write(`${setScrollRegion(1, scrollBottom())}${cursorTo(scrollBottom())}`);
+    drawBox();
+    child.stdout?.on("data", (chunk) => {
+      stdout.write(chunk);
+      scheduleBox();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr.write(chunk);
+      scheduleBox();
+    });
+    stdout.on("resize", () => {
+      stdout.write(setScrollRegion(1, scrollBottom()));
+      drawBox();
+    });
+  }
+  let released = false;
+  const cleanup = () => {
+    if (released || !sticky) {
+      return;
+    }
+    released = true;
+    clearTimeout(scheduled);
+    stdout.write(`${RESET_SCROLL_REGION}${cursorTo(size().rows)}
+`);
+  };
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  signals.forEach((signal) => process2.on(signal, () => child.kill(signal)));
+  process2.on("exit", cleanup);
+  return new Promise((resolve2, reject) => {
+    child.on("error", (error) => {
+      cleanup();
+      reject(new Error(`${bin}: ${error.message}`));
+    });
+    child.on("close", (code, signal) => {
+      cleanup();
+      resolve2(signal === null ? code ?? 0 : 1);
+    });
+  });
+}
+
+// src/cli.ts
+var EX_USAGE = 64;
+async function main() {
+  const { content, title, config, help, version, command } = parseCommandLine(argv.slice(2));
+  if (version) {
+    stdout2.write(`${package_default.version}
+`);
+    return;
+  }
+  if (help || command.length === 0) {
+    (help ? stdout2 : stderr2).write(helpText());
+    if (!help) {
+      process3.exitCode = EX_USAGE;
+    }
+    return;
+  }
+  process3.exitCode = await runWithBox(command, await loadConfig({ content, title, config }));
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  stderr2.write(`${RED}${message}${RESET}
+`);
+  process3.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@enke.dev/logbox",
+  "version": "0.0.1",
+  "license": "MIT",
+  "packageManager": "bun@1.3.14",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "description": "Wraps a long-running command and pins a configurable info box to the bottom of the terminal.",
+  "keywords": [
+    "cli",
+    "terminal",
+    "tty",
+    "dev-server",
+    "box"
+  ],
+  "author": {
+    "name": "David Enke",
+    "email": "david@enke.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/enke-dev/logbox.git"
+  },
+  "homepage": "https://enke-dev.github.io/logbox/",
+  "type": "module",
+  "bin": {
+    "logbox": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist/cli.mjs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "prepare": "bun run build",
+    "check": "tsgo --noEmit",
+    "lint": "run-p lint:*",
+    "lint:eslint": "bun --bun eslint --config eslint.config.ts",
+    "lint:prettier": "bun --bun prettier --config prettier.config.ts --check .",
+    "format": "run-p format:*",
+    "format:eslint": "bun --bun eslint --config eslint.config.ts --fix",
+    "format:prettier": "bun --bun prettier --config prettier.config.ts --write .",
+    "test": "run-p -c test:*",
+    "test:bun": "bun test --reporter=junit --reporter-outfile=reports/junit.bun.xml",
+    "test:node": "node --import tsx --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=reports/junit.node.xml \"src/**/*.spec.ts\"",
+    "dev": "bun run --bun src/cli.ts",
+    "build": "bun build ./src/cli.ts --target=node --outfile dist/cli.mjs"
+  },
+  "devDependencies": {
+    "@enke.dev/lint": "0.13.8",
+    "@tsconfig/strictest": "2.0.8",
+    "@types/bun": "1.3.14",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "eslint": "10.8.1",
+    "jiti": "2.7.0",
+    "npm-run-all2": "9.0.3",
+    "prettier": "3.9.6",
+    "tsx": "4.23.12",
+    "typescript": "6.0.3"
+  }
+}