codex-configurator 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # Codex Configurator
 
 Codex Configurator is a terminal user interface (TUI) built with Node.js, React, and Ink.
-It shows the current contents of `~/.codex/config.toml` and can reload them on demand.
+It shows the current contents of a Codex TOML configuration file and can reload it on demand.
 
 ## Requirements
 
@@ -10,19 +10,26 @@ It shows the current contents of `~/.codex/config.toml` and can reload them on d
 ## Install
 
 ```bash
-npm install
+npm i -g codex-configurator
 ```
 
 ## Usage
 
 ```bash
-npm start
+codex-configurator
 ```
 
-To run directly from an installed package:
+Optional config-path override:
 
 ```bash
-codex-configurator
+codex-configurator --config /path/to/config.toml
+```
+
+For local development in this repository:
+
+```bash
+npm install
+npm start
 ```
 
 ## Controls
@@ -33,7 +40,7 @@ codex-configurator
 - `Enter`: open selected table; for boolean settings, toggle directly; for string settings, open inline input; for other preset values, open picker
 - `Del`: unset selected value or remove selected custom `<id>` entry from `config.toml`
 - `←` / `Backspace`: move up one level (to parent table)
-- `r`: reload `~/.codex/config.toml`
+- `r`: reload the active config file
 - `q`: quit
 
 The right-hand pane shows what each setting means, plus a picker when a value has preset options.
@@ -52,7 +59,7 @@ The table view follows TOML structure, with a root catalog of common keys:
 - Selected sections such as `history`, `tui`, `feedback`, and `shell_environment_policy` also show common unset keys.
 - Attributes and subattributes are shown in strict alphabetical order.
 - Unset boolean settings display explicit defaults as `true [default]` or `false [default]`.
-- For placeholder keys like `<path>`, IDs entered in the UI are normalized under your home directory.
+- For placeholder keys like `<path>`, IDs entered in the UI are normalized under your home directory, and traversal outside home is rejected.
 
 - Dotted/table sections become navigable table nodes.
 - Inline key-value pairs are shown as leaf entries.
@@ -61,13 +68,39 @@ The table view follows TOML structure, with a root catalog of common keys:
 
 ## Configuration source
 
-The app reads from:
+By default the app reads from:
 
 ```bash
 ~/.codex/config.toml
 ```
 
-If the file is missing or unreadable, the TUI displays the read error and the expected path.
+You can override this path with either:
+
+- CLI: `--config /absolute/or/relative/path.toml`
+- Env: `CODEX_CONFIGURATOR_CONFIG_PATH`
+
+Precedence is CLI first, then environment variable, then the default path.
+If the file is missing or unreadable, the TUI displays the read error and the resolved path.
+Configuration writes are atomic and create the target file (and parent directories) when missing.
+
+## Error logging
+
+Read/write failures are appended to a JSON-lines log file.
+
+- Default path: `~/.codex-configurator-errors.log`
+- Override path: `CODEX_CONFIGURATOR_ERROR_LOG_PATH`
+- Max log size before single-file rotation: `CODEX_CONFIGURATOR_ERROR_LOG_MAX_BYTES` (default `1048576`)
+
+When the log exceeds the size limit, it is rotated to `<log-path>.1` before writing the new event.
+
+## Version checks
+
+Codex version checks are disabled by default to avoid executing unknown binaries from `PATH`.
+To enable checks, all of the following must be set:
+
+- `CODEX_CONFIGURATOR_ENABLE_VERSION_CHECK=1`
+- `CODEX_CONFIGURATOR_CODEX_BIN=/absolute/path/to/codex`
+- `CODEX_CONFIGURATOR_NPM_BIN=/absolute/path/to/npm`
 
 ## Upstream reference
 
@@ -77,9 +110,16 @@ If the file is missing or unreadable, the TUI displays the read error and the ex
 
 - `npm start`: run the TUI
 - `npm run dev`: same as `npm start`
-- `npm run lint`: syntax check for all source files
-- `npm run build`: syntax check for distributable entrypoint and modules
-- `npm test`: runs lint
+- `npm run lint`: ESLint static analysis for `index.js`, `src`, and `test`
+- `npm run build`: validates the npm package archive (`npm pack --dry-run --ignore-scripts --cache .npm-cache`)
+- `npm test`: runs the Node.js unit test suite (`node --test`)
+
+## Continuous integration
+
+GitHub Actions runs production dependency audit (`npm audit --omit=dev --audit-level=high`), `npm run lint`, `npm test`, `npm run build`, and `npm pack --dry-run` on every push and pull request across:
+
+- `ubuntu-latest`, `macos-latest`, and `windows-latest`
+- Node.js `18` and `20`
 
 ## Project structure
 

package/index.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
 
 import React, { useState, useEffect } from 'react';
-import os from 'os';
-import path from 'path';
-import { execSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import path from 'node:path';
 import { render, useInput, useApp, useStdout, Text, Box } from 'ink';
 import { CONTROL_HINT, EDIT_CONTROL_HINT } from './src/constants.js';
 import {
@@ -19,6 +18,7 @@ import {
   getReferenceOptionForPath,
   getReferenceCustomIdPlaceholder,
 } from './src/configReference.js';
+import { normalizeCustomPathId } from './src/customPathId.js';
 import { pathToKey, clamp } from './src/layout.js';
 import {
   isBackspaceKey,
@@ -57,34 +57,69 @@ const isCustomIdTableRow = (pathSegments, row) =>
   Boolean(getReferenceCustomIdPlaceholder(pathSegments));
 
 const isInlineTextMode = (mode) => mode === 'text' || mode === 'add-id';
+const VERSION_COMMAND_TIMEOUT_MS = 3000;
+const VERSION_DISABLED_LABEL = 'version check disabled';
+const VERSION_CHECK_ENABLED_ENV_VAR = 'CODEX_CONFIGURATOR_ENABLE_VERSION_CHECK';
+const CODEX_BIN_ENV_VAR = 'CODEX_CONFIGURATOR_CODEX_BIN';
+const NPM_BIN_ENV_VAR = 'CODEX_CONFIGURATOR_NPM_BIN';
+
+const runCommand = (command, args = []) =>
+  new Promise((resolve) => {
+    execFile(
+      command,
+      args,
+      {
+        encoding: 'utf8',
+        timeout: VERSION_COMMAND_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024,
+        windowsHide: true,
+      },
+      (error, stdout) => {
+        if (error) {
+          resolve('');
+          return;
+        }
+
+        resolve(String(stdout || '').trim());
+      }
+    );
+  });
 
-const normalizeCustomPathId = (value) => {
-  const trimmedValue = String(value || '').trim();
-  if (!trimmedValue) {
+const getAbsoluteCommandPath = (environmentVariableName) => {
+  const configuredPath = String(process.env[environmentVariableName] || '').trim();
+  if (!configuredPath || !path.isAbsolute(configuredPath)) {
     return '';
   }
 
-  const withoutTilde = trimmedValue.startsWith('~')
-    ? trimmedValue.slice(1)
-    : trimmedValue;
-  const relativePath = withoutTilde.replace(/^[/\\]+/, '');
-
-  return path.join(os.homedir(), relativePath);
+  return configuredPath;
 };
 
-const getCodexVersion = () => {
-  try {
-    const output = execSync('codex --version', { encoding: 'utf8', stdio: 'pipe' }).trim();
-    const firstLine = output.split('\n')[0].trim();
+const getVersionCommands = () => {
+  if (process.env[VERSION_CHECK_ENABLED_ENV_VAR] !== '1') {
+    return null;
+  }
 
-    if (!firstLine) {
-      return 'version unavailable';
-    }
+  const codexCommand = getAbsoluteCommandPath(CODEX_BIN_ENV_VAR);
+  const npmCommand = getAbsoluteCommandPath(NPM_BIN_ENV_VAR);
+  if (!codexCommand || !npmCommand) {
+    return null;
+  }
+
+  return {
+    codexCommand,
+    npmCommand,
+  };
+};
+
+const getCodexVersion = async (codexCommand) => {
+  const output = await runCommand(codexCommand, ['--version']);
+  const firstLine = output.split('\n')[0]?.trim();
 
-    return firstLine.startsWith('codex') ? firstLine : `version ${firstLine}`;
-  } catch {
+  if (!firstLine) {
     return 'version unavailable';
   }
+
+  return firstLine.startsWith('codex') ? firstLine : `version ${firstLine}`;
 };
 
 const normalizeVersion = (value) => {
@@ -120,53 +155,57 @@ const compareVersions = (left, right) => {
   return 0;
 };
 
-const getCodexUpdateStatus = () => {
-  const installed = normalizeVersion(getCodexVersion());
+const getCodexUpdateStatus = async () => {
+  const commands = getVersionCommands();
+  if (!commands) {
+    return {
+      installed: VERSION_DISABLED_LABEL,
+      latest: 'unknown',
+      status: '',
+    };
+  }
+
+  const installedLabel = await getCodexVersion(commands.codexCommand);
+  const installed = normalizeVersion(installedLabel);
 
   if (!installed) {
     return {
-      installed: 'version unavailable',
+      installed: installedLabel,
       latest: 'unknown',
       status: 'version check unavailable',
     };
   }
 
-  try {
-    const latestOutput = execSync('npm view @openai/codex version --json', {
-      encoding: 'utf8',
-      stdio: 'pipe',
-    }).trim();
-    const latest = normalizeVersion(latestOutput) || latestOutput.trim();
-
-    if (!latest) {
-      return {
-        installed,
-        latest: 'unknown',
-        status: 'version check unavailable',
-      };
-    }
-
-    const comparison = compareVersions(installed, latest);
-    if (comparison < 0) {
-      return {
-        installed,
-        latest,
-        status: 'update available',
-      };
-    }
+  const latestOutput = await runCommand(commands.npmCommand, [
+    'view',
+    '@openai/codex',
+    'version',
+    '--json',
+  ]);
+  const latest = normalizeVersion(latestOutput) || latestOutput.trim();
 
+  if (!latest) {
     return {
       installed,
-      latest,
-      status: 'up to date',
+      latest: 'unknown',
+      status: 'version check unavailable',
     };
-  } catch {
+  }
+
+  const comparison = compareVersions(installed, latest);
+  if (comparison < 0) {
     return {
       installed,
-      latest: 'unknown',
-      status: 'version check unavailable',
+      latest,
+      status: 'update available',
     };
   }
+
+  return {
+    installed,
+    latest,
+    status: 'up to date',
+  };
 };
 
 const App = () => {
@@ -187,9 +226,24 @@ const App = () => {
   const { exit } = useApp();
 
   useEffect(() => {
-    const check = getCodexUpdateStatus();
-    setCodexVersion(check.installed);
-    setCodexVersionStatus(check.status);
+    let isCancelled = false;
+
+    const loadVersionStatus = async () => {
+      const check = await getCodexUpdateStatus();
+
+      if (isCancelled) {
+        return;
+      }
+
+      setCodexVersion(check.installed);
+      setCodexVersionStatus(check.status);
+    };
+
+    loadVersionStatus();
+
+    return () => {
+      isCancelled = true;
+    };
   }, []);
 
   const currentNode = getNodeAtPath(snapshot.ok ? snapshot.data : {}, pathSegments);
@@ -316,9 +370,17 @@ const App = () => {
 
     const nextIdInput = String(editMode.draftValue || '').trim();
     const placeholder = getReferenceCustomIdPlaceholder(editMode.path);
-    const nextId = placeholder === '<path>'
-      ? normalizeCustomPathId(nextIdInput)
-      : nextIdInput;
+    let nextId = nextIdInput;
+
+    if (placeholder === '<path>') {
+      const normalizedPath = normalizeCustomPathId(nextIdInput);
+      if (!normalizedPath.ok) {
+        setEditError(normalizedPath.error);
+        return;
+      }
+
+      nextId = normalizedPath.value;
+    }
 
     if (!nextId) {
       setEditError('ID cannot be empty.');
@@ -712,7 +774,7 @@ const App = () => {
       setEditError('');
       return;
     }
-  });
+  }, { isActive: isInteractive });
 
   useEffect(() => {
     const maxOffset = Math.max(0, rows.length - listViewportHeight);

package/package.json

@@ -1,42 +1,55 @@
 {
-  "name": "codex-configurator",
-  "version": "0.1.0",
-  "description": "TOML-aware Ink TUI for Codex Configurator",
-  "main": "index.js",
-  "type": "module",
-  "keywords": [
-    "tui",
-    "terminal",
-    "cli",
-    "react",
-    "ink",
-    "node",
-    "configurator"
-  ],
-  "author": "Codex Configurator",
-  "license": "MIT",
-  "bin": {
-    "codex-configurator": "index.js"
-  },
-  "scripts": {
-    "start": "node index.js",
-    "dev": "node index.js",
-    "lint": "node --check index.js && node --check src/configHelp.js src/configParser.js src/constants.js src/interaction.js src/layout.js src/components/Header.js src/components/ConfigNavigator.js",
-    "build": "node --check index.js && node --check src/configHelp.js src/configParser.js src/constants.js src/interaction.js src/layout.js src/components/Header.js src/components/ConfigNavigator.js",
-    "test": "npm run lint",
-    "prepack": "npm run test"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "files": [
-    "index.js",
-    "src"
-  ],
-  "dependencies": {
-    "@iarna/toml": "^2.2.5",
-    "ink": "^6.2.1",
-    "react": "^19.0.0",
-    "toml": "^3.0.0"
-  }
+	"name": "codex-configurator",
+	"version": "0.2.0",
+	"description": "TOML-aware Ink TUI for Codex Configurator",
+	"main": "index.js",
+	"type": "module",
+	"keywords": [
+		"tui",
+		"terminal",
+		"cli",
+		"react",
+		"ink",
+		"node",
+		"configurator"
+	],
+	"author": "Codex Configurator",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/enriquemorenotent/codex-configurator.git"
+	},
+	"homepage": "https://github.com/enriquemorenotent/codex-configurator#readme",
+	"bugs": {
+		"url": "https://github.com/enriquemorenotent/codex-configurator/issues"
+	},
+	"funding": "https://github.com/sponsors/enriquemorenotent",
+	"bin": {
+		"codex-configurator": "index.js"
+	},
+	"scripts": {
+		"start": "node index.js",
+		"dev": "node index.js",
+		"lint": "eslint index.js src test --max-warnings=0",
+		"build": "npm pack --dry-run --ignore-scripts --cache .npm-cache",
+		"test": "node --test",
+		"prepack": "npm run lint && npm test"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"packageManager": "npm@10.9.4",
+	"files": [
+		"index.js",
+		"src"
+	],
+	"dependencies": {
+		"@iarna/toml": "^2.2.5",
+		"ink": "^6.2.1",
+		"react": "^19.0.0",
+		"toml": "^3.0.0"
+	},
+	"devDependencies": {
+		"eslint": "^8.57.1"
+	}
 }

package/src/components/ConfigNavigator.js

@@ -7,7 +7,7 @@ import {
   getConfigDefaultOption,
 } from '../configHelp.js';
 import { computePaneWidths, clamp } from '../layout.js';
-import { getNodeAtPath, buildRows, formatDetails } from '../configParser.js';
+import { getNodeAtPath, buildRows } from '../configParser.js';
 
 const MenuItem = ({ isSelected, isDimmed, isDeprecated, label }) =>
   React.createElement(

package/src/components/Header.js

@@ -21,8 +21,8 @@ export const Header = ({ codexVersion, codexVersionStatus }) =>
       React.createElement(
         Box,
         { flexDirection: 'column', marginBottom: 1, gap: 0 },
-        ...WORDMARK.map((line) =>
-          React.createElement(Text, { color: 'magentaBright', bold: true, key: `word-${line}` }, line)
+        ...WORDMARK.map((line, index) =>
+          React.createElement(Text, { color: 'magentaBright', bold: true, key: `word-${index}` }, line)
         )
       ),
     React.createElement(

package/src/configParser.js

@@ -13,8 +13,12 @@ import {
   getReferenceRootDefinitions,
   getReferenceTableDefinitions,
 } from './configReference.js';
+import { logConfiguratorError } from './errorLogger.js';
 
-export const CONFIG_PATH = path.join(os.homedir(), '.codex', 'config.toml');
+export const CONFIG_PATH_ENV_VAR = 'CODEX_CONFIGURATOR_CONFIG_PATH';
+const CONFIG_PATH_FLAG = '--config';
+const DEFAULT_CONFIG_FILE_SEGMENTS = ['.codex', 'config.toml'];
+export const DEFAULT_CONFIG_PATH = path.join(os.homedir(), ...DEFAULT_CONFIG_FILE_SEGMENTS);
 export const MAX_DETAIL_CHARS = 2200;
 const MAX_ARRAY_PREVIEW_ITEMS = 3;
 const MAX_ARRAY_PREVIEW_CHARS = 52;
@@ -77,21 +81,91 @@ const formatArrayPreview = (value) => {
   return truncateText(joined, MAX_ARRAY_PREVIEW_CHARS);
 };
 
-export const readConfig = () => {
+const expandHomePath = (value, homeDir) => {
+  if (value === '~') {
+    return homeDir;
+  }
+
+  if (value.startsWith('~/') || value.startsWith('~\\')) {
+    return path.join(homeDir, value.slice(2));
+  }
+
+  return value;
+};
+
+const normalizeConfiguredPath = (value, homeDir) => {
+  const normalizedValue = typeof value === 'string' ? value.trim() : '';
+  if (!normalizedValue) {
+    return '';
+  }
+
+  const expanded = expandHomePath(normalizedValue, homeDir);
+  return path.resolve(expanded);
+};
+
+const getCliConfigPath = (argv = process.argv.slice(2)) => {
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = typeof argv[index] === 'string' ? argv[index].trim() : '';
+    if (!argument) {
+      continue;
+    }
+
+    if (argument === CONFIG_PATH_FLAG) {
+      const nextArgument = argv[index + 1];
+      return typeof nextArgument === 'string' ? nextArgument : '';
+    }
+
+    if (argument.startsWith(`${CONFIG_PATH_FLAG}=`)) {
+      return argument.slice(CONFIG_PATH_FLAG.length + 1);
+    }
+  }
+
+  return '';
+};
+
+export const resolveConfigPath = ({
+  argv = process.argv.slice(2),
+  env = process.env,
+  homeDir = os.homedir(),
+} = {}) => {
+  const cliConfiguredPath = normalizeConfiguredPath(getCliConfigPath(argv), homeDir);
+  if (cliConfiguredPath) {
+    return cliConfiguredPath;
+  }
+
+  const envConfiguredPath = normalizeConfiguredPath(env?.[CONFIG_PATH_ENV_VAR], homeDir);
+  if (envConfiguredPath) {
+    return envConfiguredPath;
+  }
+
+  return path.join(homeDir, ...DEFAULT_CONFIG_FILE_SEGMENTS);
+};
+
+export const CONFIG_PATH = resolveConfigPath();
+
+export const readConfig = (configPath = CONFIG_PATH) => {
   try {
-    const fileContents = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const targetPath = configPath;
+    const fileContents = fs.readFileSync(targetPath, 'utf8');
     const data = toml.parse(fileContents);
 
     return {
       ok: true,
-      path: CONFIG_PATH,
+      path: targetPath,
       data,
     };
   } catch (error) {
+    const targetPath = configPath;
+    const errorMessage = error?.message || 'Unable to read or parse configuration file.';
+    logConfiguratorError('config.read.failed', {
+      configPath: targetPath,
+      error: errorMessage,
+    });
+
     return {
       ok: false,
-      path: CONFIG_PATH,
-      error: error?.message || 'Unable to read or parse configuration file.',
+      path: targetPath,
+      error: errorMessage,
     };
   }
 };
@@ -99,17 +173,57 @@ export const readConfig = () => {
 const normalizeFilePath = (outputPath) => outputPath || CONFIG_PATH;
 
 export const writeConfig = (data, outputPath = CONFIG_PATH) => {
+  const targetPath = normalizeFilePath(outputPath);
+  const directoryPath = path.dirname(targetPath);
+  const fileName = path.basename(targetPath);
+  const tempPath = path.join(
+    directoryPath,
+    `.${fileName}.${process.pid}.${Date.now()}.tmp`
+  );
+
   try {
+    if (!fs.existsSync(directoryPath)) {
+      fs.mkdirSync(directoryPath, { recursive: true, mode: 0o700 });
+    }
+
     const payload = stringify(data);
-    fs.writeFileSync(normalizeFilePath(outputPath), `${payload}\n`);
+    let tempFd = null;
+
+    try {
+      tempFd = fs.openSync(tempPath, 'wx', 0o600);
+      fs.writeFileSync(tempFd, `${payload}\n`, 'utf8');
+      fs.fsyncSync(tempFd);
+      fs.closeSync(tempFd);
+      tempFd = null;
+
+      fs.renameSync(tempPath, targetPath);
+    } finally {
+      if (tempFd !== null) {
+        try {
+          fs.closeSync(tempFd);
+        } catch {}
+      }
+
+      if (fs.existsSync(tempPath)) {
+        try {
+          fs.unlinkSync(tempPath);
+        } catch {}
+      }
+    }
 
     return {
       ok: true,
     };
   } catch (error) {
+    const errorMessage = error?.message || 'Unable to write configuration file.';
+    logConfiguratorError('config.write.failed', {
+      configPath: targetPath,
+      error: errorMessage,
+    });
+
     return {
       ok: false,
-      error: error?.message || 'Unable to write configuration file.',
+      error: errorMessage,
     };
   }
 };

package/src/configReference.js

@@ -1,4 +1,7 @@
-import CONFIG_REFERENCE_DATA from './reference/config-reference.json' with { type: 'json' };
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const CONFIG_REFERENCE_DATA = require('./reference/config-reference.json');
 
 const DOCUMENT_ID = 'config.toml';
 const PLACEHOLDER_SEGMENT = /^<[^>]+>$/;

package/src/customPathId.js

@@ -0,0 +1,42 @@
+import os from 'os';
+import path from 'path';
+
+const normalizePathSegments = (value) =>
+  String(value || '')
+    .split(/[\\/]+/)
+    .filter((segment) => segment.length > 0)
+    .join(path.sep);
+
+const resolveCustomPath = (value, homePath) => {
+  const withoutTilde = value.startsWith('~') ? value.slice(1) : value;
+  const relativePath = normalizePathSegments(withoutTilde.replace(/^[/\\]+/, ''));
+  return path.resolve(homePath, relativePath);
+};
+
+const isWithinHomePath = (resolvedPath, homePath) => {
+  const relative = path.relative(homePath, resolvedPath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+};
+
+export const normalizeCustomPathId = (value, homePath = os.homedir()) => {
+  const trimmedValue = String(value || '').trim();
+  if (!trimmedValue) {
+    return {
+      ok: false,
+      error: 'ID cannot be empty.',
+    };
+  }
+
+  const resolvedPath = resolveCustomPath(trimmedValue, homePath);
+  if (!isWithinHomePath(resolvedPath, homePath)) {
+    return {
+      ok: false,
+      error: `Path must stay inside ${homePath}.`,
+    };
+  }
+
+  return {
+    ok: true,
+    value: resolvedPath,
+  };
+};

package/src/errorLogger.js

@@ -0,0 +1,70 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const DEFAULT_ERROR_LOG_PATH = path.join(os.homedir(), '.codex-configurator-errors.log');
+const DEFAULT_ERROR_LOG_MAX_BYTES = 1024 * 1024;
+const ERROR_LOG_MAX_BYTES_ENV_VAR = 'CODEX_CONFIGURATOR_ERROR_LOG_MAX_BYTES';
+
+const getErrorLogPath = () =>
+  process.env.CODEX_CONFIGURATOR_ERROR_LOG_PATH || DEFAULT_ERROR_LOG_PATH;
+
+const parsePositiveInteger = (value) => {
+  const parsed = Number.parseInt(String(value || ''), 10);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return null;
+  }
+
+  return parsed;
+};
+
+const getErrorLogMaxBytes = () =>
+  parsePositiveInteger(process.env[ERROR_LOG_MAX_BYTES_ENV_VAR]) || DEFAULT_ERROR_LOG_MAX_BYTES;
+
+const ensureLogDirectory = (logPath) => {
+  const directoryPath = path.dirname(logPath);
+  if (!fs.existsSync(directoryPath)) {
+    fs.mkdirSync(directoryPath, { recursive: true, mode: 0o700 });
+  }
+};
+
+const rotateLogFileIfNeeded = (logPath, maxBytes) => {
+  try {
+    const stats = fs.statSync(logPath);
+    if (!stats.isFile() || stats.size < maxBytes) {
+      return;
+    }
+
+    const rotatedPath = `${logPath}.1`;
+    if (fs.existsSync(rotatedPath)) {
+      fs.unlinkSync(rotatedPath);
+    }
+
+    fs.renameSync(logPath, rotatedPath);
+  } catch {}
+};
+
+export const logConfiguratorError = (event, details = {}) => {
+  const payload = {
+    timestamp: new Date().toISOString(),
+    event: String(event || 'unknown'),
+    ...details,
+  };
+  const logPath = getErrorLogPath();
+  const maxBytes = getErrorLogMaxBytes();
+
+  try {
+    ensureLogDirectory(logPath);
+    rotateLogFileIfNeeded(logPath, maxBytes);
+    fs.appendFileSync(logPath, `${JSON.stringify(payload)}\n`, 'utf8');
+    return {
+      ok: true,
+      path: logPath,
+    };
+  } catch {
+    return {
+      ok: false,
+      path: logPath,
+    };
+  }
+};