@deployanyway/error-translator 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.1 — 2026-10-08
+
+- Correct npm installation and npx documentation after the initial publication.
+- Add a searchable, humorous package description and relevant npm keywords.
+- No API, CLI behavior, or dependency changes.
+
+## 0.1.0 — 2026-10-08
+
+- Plain-English translations for ECONNREFUSED, ENOENT, EADDRINUSE, MODULE_NOT_FOUND, ERR_MODULE_NOT_FOUND, and TypeError.
+- Structured results, text rendering, and CLI with JSON output.
+- Automated tests, linting, formatting, 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,143 @@
-# Temporary Holding Version
+# error-translator
 
-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.
+Plain-English Node.js error explanations and debugging tips, because the stack trace has chosen violence.
+
+```text
+Connection refused
+
+What happened:
+The application tried to connect to a service, but nothing accepted the connection.
+
+Likely causes:
+- The service is not running
+- The host or port is incorrect
+- A firewall actively rejected the connection
+
+Try:
+- Confirm that the service is running and listening on the configured host and port.
+- Check connection settings and firewall rules.
+```
+
+## Installation
+
+Available on npm. Requires Node 22 or later.
+You can also run from source with Node 22 or 24:
+
+```sh
+git clone https://github.com/DeployAnyway/error-translator.git
+cd error-translator
+git checkout main
+npm ci
+node bin/cli.js ECONNREFUSED
+```
+
+Install from npm:
+
+```sh
+npm install @deployanyway/error-translator
+```
+
+## Quick start
+
+```js
+import {
+  translateError,
+  renderTranslation,
+} from "@deployanyway/error-translator";
+
+const result = translateError("ECONNREFUSED");
+console.log(result.suggestions);
+console.log(renderTranslation(result));
+```
+
+## CLI example
+
+```sh
+node bin/cli.js "TypeError: value is not a function" --json
+```
+
+Run with npx: `npx @deployanyway/error-translator ECONNREFUSED`.
+
+## API and options
+
+### `translateError(error, { mode = 'plain' } = {})`
+
+Accepts a nonempty string, an Error, or an object with string `code`, `name`,
+or `message` fields. Returns a fresh structured object with `code`, `title`,
+`explanation`, `likelyCauses` (string array), `suggestions` (string array), and `mode`.
+
+An explicit code takes precedence, followed by a recognized name, then a
+case-sensitive whole-word match in the message. Unknown errors return general
+guidance with code `UNKNOWN`, or preserve an explicit unknown code.
+Invalid input throws TypeError; unsupported modes throw RangeError.
+Only `plain` is available in this MVP. Humorous modes are planned.
+
+### `renderTranslation(result)`
+
+Returns readable text. Does not print, mutate the result, or exit the process.
+Invalid result shapes throw TypeError.
+
+### Built-in errors
+
+| Code/name            | Guidance                                   |
+| -------------------- | ------------------------------------------ |
+| ECONNREFUSED         | Service availability, host, port, firewall |
+| ENOENT               | Missing paths and working directories      |
+| EADDRINUSE           | Port conflicts and duplicate instances     |
+| MODULE_NOT_FOUND     | CommonJS dependencies and paths            |
+| ERR_MODULE_NOT_FOUND | ES module dependencies, paths, extensions  |
+| TypeError            | Unexpected types and null/undefined values |
+
+Translations describe likely causes, not a diagnosis. Keep the original error
+and stack trace for context. No AI API or remote service is used.
+
+## CLI reference
+
+`error-translator <code or message> [options]`
+
+| Option            | Behavior              |
+| ----------------- | --------------------- |
+| `--help`, `-h`    | Show usage            |
+| `--version`, `-v` | Show package version  |
+| `--json`          | Print structured JSON |
+| `--mode plain`    | Select plain mode     |
+
+Quote messages containing spaces or shell punctuation. Use `--` before a message
+beginning with a dash. No stdin support is included in the MVP.
+Exit code 0 means translation/help/version succeeded, including unknown errors.
+Exit code 2 means invalid arguments. The library never exits.
+
+## Examples and development
+
+```sh
+npm ci
+node examples/basic.js
+npm test
+npm run lint
+npm run format:check
+npm pack --dry-run
+```
+
+ES modules, Node's test runner, zero production dependencies. CI checks Node 22
+and 24. Error definitions live in `src/definitions.js`; API and renderer in
+`src/index.js`; CLI in `bin/cli.js`. Only runtime files, README, MIT license,
+changelog, and package metadata are packaged.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Accurate, actionable guidance and tests
+are welcome.
+
+## 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,38 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { URL } from "node:url";
+import { readFileSync } from "node:fs";
+import { translateError, renderTranslation } from "../src/index.js";
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      json: { type: "boolean" },
+      mode: { type: "string", default: "plain" },
+    },
+  });
+  if (values.help) {
+    console.log(
+      'Usage: error-translator <error code or quoted message> [--json] [--mode plain]\n\nTranslate errors into human-readable guidance.\n\nOptions:\n  -h, --help     Show help\n  -v, --version  Show version\n  --json         Print a structured JSON result\n  --mode plain   Translation mode (MVP: plain only)\n\nExamples:\n  error-translator ECONNREFUSED\n  error-translator "TypeError: value is not a function" --json\n\nExit codes: 0 translation/help/version; 2 invalid arguments.',
+    );
+  } else if (values.version) {
+    console.log(
+      JSON.parse(
+        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+      ).version,
+    );
+  } else {
+    const result = translateError(positionals.join(" "), { mode: values.mode });
+    console.log(
+      values.json ? JSON.stringify(result, null, 2) : renderTranslation(result),
+    );
+  }
+} catch (error) {
+  console.error(
+    `error-translator: ${error.message}\nRun with --help for usage.`,
+  );
+  process.exitCode = 2;
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@deployanyway/error-translator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Plain-English Node.js error explanations and debugging tips, because the stack trace has chosen violence.",
+  "type": "module",
+  "exports": "./src/index.js",
+  "bin": {
+    "error-translator": "./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/error-translator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DeployAnyway/error-translator/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "eslint": "^10.12.0",
+    "prettier": "^3.6.2"
+  },
+  "keywords": [
+    "nodejs",
+    "javascript",
+    "cli",
+    "developer-tools",
+    "debugging",
+    "error-messages",
+    "error-translator",
+    "plain-english"
+  ]
+}

package/src/definitions.js

@@ -0,0 +1,83 @@
+// Keep technical guidance here so contributors can add errors without changing logic.
+export const definitions = {
+  ECONNREFUSED: {
+    title: "Connection refused",
+    explanation:
+      "The application tried to connect to a service, but nothing accepted the connection.",
+    likelyCauses: [
+      "The service is not running",
+      "The host or port is incorrect",
+      "A firewall actively rejected the connection",
+    ],
+    suggestions: [
+      "Confirm that the service is running and listening on the configured host and port.",
+      "Check connection settings and firewall rules.",
+    ],
+  },
+  ENOENT: {
+    title: "File or directory not found",
+    explanation:
+      "The application tried to use a filesystem path that does not exist.",
+    likelyCauses: [
+      "The path is misspelled",
+      "The file was moved or deleted",
+      "A relative path is being resolved from an unexpected working directory",
+    ],
+    suggestions: [
+      "Check the full path and the current working directory.",
+      "Create the required file or directory if it should exist.",
+    ],
+  },
+  EADDRINUSE: {
+    title: "Address already in use",
+    explanation:
+      "The application tried to listen on an address and port that another listener already uses.",
+    likelyCauses: [
+      "Another instance of the application is running",
+      "Another service uses the same port",
+    ],
+    suggestions: [
+      "Identify the process using the port before stopping it.",
+      "Choose a different available port or stop the duplicate instance.",
+    ],
+  },
+  MODULE_NOT_FOUND: {
+    title: "Module not found",
+    explanation:
+      "Node.js could not resolve a module requested by the application.",
+    likelyCauses: [
+      "A dependency is missing",
+      "The module path is incorrect",
+      "A dependency references a missing module",
+    ],
+    suggestions: [
+      "Check the missing module name and the require stack.",
+      "Install declared dependencies with npm install and verify local paths.",
+    ],
+  },
+  ERR_MODULE_NOT_FOUND: {
+    title: "ES module not found",
+    explanation: "Node.js could not resolve an imported ES module.",
+    likelyCauses: [
+      "A dependency is missing",
+      "The import path or file extension is incorrect",
+    ],
+    suggestions: [
+      "Install declared dependencies and verify the import path.",
+      "Include the file extension for relative Node.js ES module imports.",
+    ],
+  },
+  TypeError: {
+    title: "Unexpected value type",
+    explanation:
+      "An operation received a value it cannot use, such as calling a non-function or reading a property of undefined.",
+    likelyCauses: [
+      "A value is null or undefined",
+      "A value has a different type than expected",
+    ],
+    suggestions: [
+      "Inspect the value at the first relevant line in the stack trace.",
+      "Check inputs and return values before accessing properties or calling functions.",
+    ],
+  },
+};

package/src/index.js

@@ -0,0 +1,93 @@
+import { definitions } from "./definitions.js";
+
+/**
+ * Translate a nonempty string, Error, or error-like object with a code/name/message.
+ * Explicit codes take precedence over names and message matching.
+ * @param {string | Error | {code?: string, name?: string, message?: string}} error
+ * @param {{mode?: 'plain'}} [options]
+ * @returns {{code: string, title: string, explanation: string, likelyCauses: string[], suggestions: string[], mode: string}}
+ */
+export function translateError(error, options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("Options must be an object.");
+  }
+  const mode = options.mode ?? "plain";
+  if (mode !== "plain") throw new RangeError("Supported modes: plain.");
+  let code;
+  let name;
+  let message;
+  if (typeof error === "string") {
+    message = error.trim();
+  } else if (error && typeof error === "object" && !Array.isArray(error)) {
+    for (const field of ["code", "name", "message"]) {
+      if (error[field] !== undefined && typeof error[field] !== "string") {
+        throw new TypeError(`Error ${field} must be a string.`);
+      }
+    }
+    code = error.code?.trim();
+    name = error.name?.trim();
+    message = error.message?.trim();
+  } else {
+    throw new TypeError(
+      "Provide a nonempty error string or error-like object.",
+    );
+  }
+  if (!code && !name && !message)
+    throw new TypeError(
+      "Provide a nonempty error string or error-like object.",
+    );
+  const matched =
+    code ||
+    (Object.hasOwn(definitions, name ?? "") ? name : undefined) ||
+    Object.keys(definitions).find((key) =>
+      new RegExp(`\\b${key}\\b`).test(message ?? ""),
+    );
+  const definition = Object.hasOwn(definitions, matched ?? "")
+    ? definitions[matched]
+    : undefined;
+  const fallback = {
+    title: "Unrecognized error",
+    explanation: "No built-in translation matches this error yet.",
+    likelyCauses: [],
+    suggestions: [
+      "Read the original error and inspect the first relevant line in its stack trace.",
+      "Check the documentation for the component that reported the error.",
+    ],
+  };
+  const result = definition ?? fallback;
+  return {
+    code: matched ?? "UNKNOWN",
+    ...result,
+    likelyCauses: [...result.likelyCauses],
+    suggestions: [...result.suggestions],
+    mode,
+  };
+}
+
+/** Render a structured translation as readable text without logging or exiting. */
+export function renderTranslation(result) {
+  if (
+    !result ||
+    typeof result.title !== "string" ||
+    typeof result.explanation !== "string" ||
+    !Array.isArray(result.likelyCauses) ||
+    !Array.isArray(result.suggestions) ||
+    ![...result.likelyCauses, ...result.suggestions].every(
+      (item) => typeof item === "string",
+    )
+  ) {
+    throw new TypeError("Provide a structured translation result.");
+  }
+  return [
+    result.title,
+    `What happened:\n${result.explanation}`,
+    ...(result.likelyCauses.length
+      ? [
+          `Likely causes:\n${result.likelyCauses.map((item) => `- ${item}`).join("\n")}`,
+        ]
+      : []),
+    ...(result.suggestions.length
+      ? [`Try:\n${result.suggestions.map((item) => `- ${item}`).join("\n")}`]
+      : []),
+  ].join("\n\n");
+}