|
| 1 | +/** |
| 2 | + * @module processes |
| 3 | + * @description Error formatting and hint utilities for backend crash diagnostics. |
| 4 | + * Parses zerolog console output, strips ANSI codes, and maps known error patterns |
| 5 | + * to actionable user-facing messages shown in the crash dialog. |
| 6 | + */ |
| 7 | + |
| 8 | +/** |
| 9 | + * List of known error patterns with human-readable messages and fix advice. |
| 10 | + * Each entry is matched against the raw stripped stderr output. |
| 11 | + */ |
| 12 | +const ERROR_HINTS = [ |
| 13 | + { |
| 14 | + pattern: /bind: The requested address is not valid/, |
| 15 | + message: "Network address unavailable", |
| 16 | + advice: |
| 17 | + "The configured IP address doesn't exist on this machine. Check your network adapter or ADJ.", |
| 18 | + }, |
| 19 | + { |
| 20 | + pattern: /failed to start UDP server/, |
| 21 | + message: "UDP server failed to start", |
| 22 | + advice: "Another process may already be using this port.", |
| 23 | + }, |
| 24 | + { |
| 25 | + pattern: /jsonschema/, |
| 26 | + message: "ADJ Validator dependency missing", |
| 27 | + advice: |
| 28 | + "Install the required Python package by running: pip install jsonschema==4.25.0", |
| 29 | + }, |
| 30 | + { |
| 31 | + pattern: /No Python interpreter found/, |
| 32 | + message: "Python not found", |
| 33 | + advice: |
| 34 | + "Install Python 3 and make sure it is accessible via 'python3', 'python', or 'py' in your PATH.", |
| 35 | + }, |
| 36 | + { |
| 37 | + pattern: /ADJ Validator failed with error/, |
| 38 | + message: "ADJ validation failed", |
| 39 | + advice: |
| 40 | + "Your ADJ files contain schema errors. Check the ADJ validator log file in the logs folder for details.", |
| 41 | + }, |
| 42 | + { |
| 43 | + pattern: /error reading config file/, |
| 44 | + message: "Config file not found", |
| 45 | + advice: |
| 46 | + "The configuration file could not be read. Check that the config file path is correct and the file exists.", |
| 47 | + }, |
| 48 | + { |
| 49 | + pattern: /error unmarshaling toml file/, |
| 50 | + message: "Config file has errors", |
| 51 | + advice: |
| 52 | + "The configuration file contains invalid TOML. Check the config file for syntax or type errors.", |
| 53 | + }, |
| 54 | + { |
| 55 | + pattern: /setting up ADJ/, |
| 56 | + message: "ADJ not available", |
| 57 | + advice: |
| 58 | + "Could not load the ADJ. If this is your first run, connect to the internet so the ADJ can be downloaded.", |
| 59 | + }, |
| 60 | +]; |
| 61 | + |
| 62 | +/** |
| 63 | + * Reformats a single stripped zerolog console line into a readable block. |
| 64 | + * Zerolog console format: "TIME LEVEL FILE > message key=value ..." |
| 65 | + * @param {string} line - A single log line with ANSI codes already stripped. |
| 66 | + * @returns {string} A formatted multi-line string with level, file, and key-value pairs on separate lines. |
| 67 | + * @example |
| 68 | + * formatLine("11:43AM FTL setup_transport.go:143 > failed to start UDP server error=\"some error\""); |
| 69 | + * // "[FTL] at setup_transport.go:143\n failed to start UDP server\n error: \"some error\"" |
| 70 | + */ |
| 71 | +function formatLine(line) { |
| 72 | + const m = line.match(/^\S+\s+(\S+)\s+(\S+)\s+>\s+(.*)/); |
| 73 | + if (!m) return line; |
| 74 | + const [, level, file, rest] = m; |
| 75 | + const body = rest.replace( |
| 76 | + /\s+(\w+)=("(?:[^"\\]|\\.)*"|\S+)/g, |
| 77 | + "\n $1: $2", |
| 78 | + ); |
| 79 | + return `[${level}] at ${file}\n ${body.trim()}`; |
| 80 | +} |
| 81 | + |
| 82 | +/** |
| 83 | + * Formats a full multi-line stderr output by reformatting each zerolog line. |
| 84 | + * @param {string} text - Raw stderr text with ANSI codes already stripped. |
| 85 | + * @returns {string} Formatted text with each log line reformatted for readability. |
| 86 | + * @example |
| 87 | + * formatBackendError("11:43AM FTL file.go:10 > something failed error=\"bad\""); |
| 88 | + */ |
| 89 | +function formatBackendError(text) { |
| 90 | + return text.split("\n").filter(Boolean).map(formatLine).join("\n\n"); |
| 91 | +} |
| 92 | + |
| 93 | +/** |
| 94 | + * Returns a user-facing error message by matching the raw error against known patterns. |
| 95 | + * If a match is found, prepends a hint and advice to the formatted error. |
| 96 | + * Falls back to the formatted error text if no pattern matches. |
| 97 | + * @param {string} raw - Raw stripped stderr text used for pattern matching. |
| 98 | + * @param {string} formatted - Pre-formatted version of the error for display. |
| 99 | + * @returns {string} The final message to show in the crash dialog. |
| 100 | + * @example |
| 101 | + * getHint("failed to start UDP server ...", "[FTL] at ..."); |
| 102 | + * // "UDP server failed to start\n\nAnother process may already be using this port.\n\n[FTL] at ..." |
| 103 | + */ |
| 104 | +function getHint(raw, formatted) { |
| 105 | + const match = ERROR_HINTS.find(({ pattern }) => pattern.test(raw)); |
| 106 | + return match |
| 107 | + ? `${match.message}\n\n${match.advice}\n\n${formatted}` |
| 108 | + : formatted; |
| 109 | +} |
| 110 | + |
| 111 | +export { formatBackendError, getHint }; |
0 commit comments