Prepare error-translator 0.3: batches, stdin and shared quality gates

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,15 @@
+---
+name: Bug report
+about: Help us reproduce a real problem
+labels: bug
+---
+
+Version, Node version, OS, shell and terminal/font:
+
+Minimal command or API call (remove sensitive data):
+
+Expected behavior:
+
+Actual output and exit status:
+
+Does --no-color or change the result?

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature request
+about: A useful idea with questionable priorities
+labels: enhancement
+---
+
+Developer problem:
+
+Example command/API and expected output:
+
+Compatibility, accessibility and offline-runtime considerations:

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Behavior
+
+What does a user see before and after?
+
+## Compatibility
+
+Describe API/output changes and migration requirements.
+
+## Validation
+
+List checks and meaningful regression coverage. Confirm workplace-safe humor and useful error handling. No npm publication is implied by this PR.

.github/workflows/ci.yml

@@ -4,18 +4,26 @@ permissions:
   contents: read
 jobs:
   check:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         node: [22, 24]
+        os: [ubuntu-latest]
+        include:
+          - { os: windows-latest, node: 24 }
+          - { os: macos-latest, node: 24 }
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node }}
           cache: npm
       - run: npm ci
+      - run: npm run build
       - run: npm run lint
       - run: npm run format:check
-      - run: npm test
+      - run: npm run coverage
+      - run: npm run test:types
+      - run: npm run verify:package
       - run: npm pack --dry-run
+      - run: npm audit --omit=dev --audit-level=high

.gitignore

@@ -3,3 +3,5 @@ node_modules/
 coverage/
 .env
 .env.*
+
+dist/

.prettierignore

@@ -1,2 +1,5 @@
 node_modules/
 package-lock.json
+
+dist/
+coverage/

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0 — 2026-10-08
+
+- Useful structured API/CLI additions described in README.
+- TypeScript declarations, CommonJS entry, coverage gates and installed archive checks.
+- Linux Node 22/24 plus Windows/macOS Node 24 CI.
+
 ## 0.2.0 — 2026-10-08
 
 - Rubber-duck translations: Keep the debugging guidance, add workplace-safe rubber-duck commentary. Plain output remains the default.

CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Community conduct
+
+Be kind, specific and curious. Welcome beginners, respect different backgrounds, and critique code without attacking people. Harassment, discrimination, threats and publishing private information are not welcome. Keep humor workplace-safe.
+
+Maintainers may remove harmful contributions and restrict repeated misconduct. Report conduct concerns privately through a maintainer's GitHub profile contact method; do not post sensitive details in public issues. Maintainers should explain decisions respectfully and handle reports confidentially where possible.

CONTRIBUTING.md

@@ -1,20 +1,7 @@
 # Contributing
 
-Welcome! Useful first, funny second. Keep guidance accurate and workplace-safe.
+Welcome to DeployAnyway: tools for developers who probably know better. Keep the core independently useful, offline, and workplace-safe. Use Node 22.13+ or 24, npm ci and a feature branch.
 
-Use Node 22 or 24. Fork the repository, create a feature branch, and run:
+Source lives in src/; CLI orchestration is measured alongside the API. Add meaningful behavior and failure tests. Run npm run build, npm run format, npm run lint, npm run format:check, npm run coverage, npm run test:types, npm run verify:package and npm audit.
 
-```sh
-npm ci
-npm run lint
-npm run format:check
-npm test
-```
-
-Add error definitions to `src/definitions.js`. Include a clear explanation,
-likely causes, actionable suggestions, and tests for matching and edge cases.
-Avoid recommending blanket permission changes or stopping unidentified processes.
-Run `npm run format` before opening a PR. Describe the behavior change and checks.
-
-Open an issue to discuss new modes or larger API changes first. No AI service,
-telemetry, or production dependency is required for the MVP.
+Coverage gates: 90% statements/lines/functions and 85% branches. Archive checks install a temporary local tarball and never publish. Document API/output changes and show a concrete use case in your PR. See CODE_OF_CONDUCT.md and SECURITY.md. Release candidates require explicit publication approval.

MIGRATION.md

@@ -0,0 +1,5 @@
+# 0.3.0 migration
+
+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.

README.md

@@ -1,5 +1,7 @@
 # error-translator
 
+> **Version 0.3.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%2Ferror-translator)](https://www.npmjs.com/package/@deployanyway/error-translator)
 [![CI](https://github.com/DeployAnyway/error-translator/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DeployAnyway/error-translator/actions/workflows/ci.yml)
 
@@ -158,3 +160,44 @@ API (import the named functions from this package):
 ```js
 translateError("ENOENT", { mode: "rubber-duck" });
 ```
+
+## Ordered error batches and pipes
+
+```js
+import { translateErrors, listErrors } from "@deployanyway/error-translator";
+const results = translateErrors(["ENOENT", { code: "ECONNREFUSED" }], {
+  mode: "rubber-duck",
+});
+console.log(results[0].suggestions);
+console.log(listErrors());
+```
+
+Batches accept 1–100 errors in order, fail on malformed entries and return independent arrays. This is deterministic guidance, not diagnosis. Unknown errors remain unknown: keep the original stack.
+
+```sh
+echo "ECONNREFUSED" | node bin/cli.js --mode rubber-duck
+node bin/cli.js --batch --json < errors.json
+node bin/cli.js --list --json
+```
+
+Without arguments, read UTF-8 stdin (maximum 256 KiB). Arguments take precedence. --batch expects a JSON array; --json emits an array of results. --list catalogs supported codes. Status 0 means translated, including unknown errors; status 2 means invalid input.
+
+## Run from source
+
+```sh
+git clone --branch main https://github.com/DeployAnyway/error-translator.git
+cd error-translator
+npm ci
+npm run build
+node bin/cli.js --help
+```
+
+## Candidate quality standard
+
+Version 0.3 provides useful declaration types, ESM/CommonJS exports, installed-archive checks, and coverage gates (90% statements/lines/functions, 85% branches). CI covers Linux Node 22/24 and Windows/macOS Node 24. Node 22.13+ is required. No runtime dependencies, telemetry or network requests.
+
+From a source checkout: npm ci, npm run build, npm run coverage, npm run test:types, npm run verify:package. Pack verification installs a temporary local archive and checks module entries, types, executable and offline npm exec.
+
+[Contribution guide](CONTRIBUTING.md) · [Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) · [Roadmap](ROADMAP.md) · [Migration](MIGRATION.md).
+
+**Tools for developers who probably know better.** Software nobody requested, built with questionable priorities, and shipped with absolute confidence!

RELEASE-NOTES.md

@@ -0,0 +1,3 @@
+# 0.3.0 — 2026-10-08
+
+Adds useful API/CLI capabilities, TypeScript and CommonJS, coverage and installed-archive gates, and consistent contributor documentation. See README and MIGRATION.md for behavior and compatibility. Published through the repository’s trusted GitHub Actions workflow.

ROADMAP.md

@@ -0,0 +1,13 @@
+# Roadmap
+
+## Now
+
+Useful structured APIs, explicit validation, types, ESM/CommonJS, installed-archive checks, coverage gates, cross-platform CI and honest release-candidate documentation.
+
+## Next
+
+Collect user feedback and real integrations. Prioritize evidence-based improvements over more flags.
+
+## Later
+
+Optional adapters to other DeployAnyway tools through public APIs or pipes. Keep runtime dependencies and telemetry out unless justified separately.

SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+The package works offline, without telemetry, network requests, shell execution or executable character loading. Avoid logging secrets. Treat user-provided messages as untrusted data; terminal emulators can interpret control sequences. These tools are not redaction or terminal-sanitization boundaries.
+
+Use GitHub Security → Report a vulnerability if available, or contact a maintainer privately through their GitHub profile. Include affected version, reproduction and impact; do not post credentials or exploit details in public issues. No response-time guarantee is promised.
+
+The 0.3 feature branch is an unreleased candidate. Visual output is not a machine-readable protocol or security boundary; use JSON for automation.

bin/cli.js

@@ -1,38 +1,2 @@
 #!/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|rubber-duck]\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|rubber-duck   Keep useful guidance; add duck commentary\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;
-}
+import "../src/cli.js";

eslint.config.js

@@ -1,13 +1,13 @@
 export default [
   {
-    ignores: ["node_modules/**"],
+    ignores: ["node_modules/**", "dist/**", "coverage/**"],
   },
   {
     files: ["**/*.js"],
     languageOptions: {
       ecmaVersion: "latest",
       sourceType: "module",
-      globals: { console: "readonly", process: "readonly" },
+      globals: { console: "readonly", process: "readonly", Buffer: "readonly" },
     },
     rules: {
       "no-unused-vars": "error",

index.d.cts

@@ -0,0 +1,23 @@
+export type ErrorInput =
+  string | Error | { code?: string; name?: string; message?: string };
+export interface TranslationOptions {
+  mode?: "plain" | "rubber-duck";
+}
+export interface Translation {
+  code: string;
+  title: string;
+  explanation: string;
+  likelyCauses: string[];
+  suggestions: string[];
+  mode: "plain" | "rubber-duck";
+}
+export function translateError(
+  error: ErrorInput,
+  options?: TranslationOptions,
+): Translation;
+export function translateErrors(
+  errors: ErrorInput[],
+  options?: TranslationOptions,
+): Translation[];
+export function renderTranslation(result: Translation): string;
+export function listErrors(): string[];

index.d.ts

@@ -0,0 +1,23 @@
+export type ErrorInput =
+  string | Error | { code?: string; name?: string; message?: string };
+export interface TranslationOptions {
+  mode?: "plain" | "rubber-duck";
+}
+export interface Translation {
+  code: string;
+  title: string;
+  explanation: string;
+  likelyCauses: string[];
+  suggestions: string[];
+  mode: "plain" | "rubber-duck";
+}
+export function translateError(
+  error: ErrorInput,
+  options?: TranslationOptions,
+): Translation;
+export function translateErrors(
+  errors: ErrorInput[],
+  options?: TranslationOptions,
+): Translation[];
+export function renderTranslation(result: Translation): string;
+export function listErrors(): string[];