feat: rc file

BCsabaEngine · BCsabaEngine · commit e2e1d21de8e6 · 2025-12-03T19:31:58.000+01:00
diff --git a/.svelteesp32rc.example.json b/.svelteesp32rc.example.json
@@ -0,0 +1,13 @@
+{
+  "engine": "psychic",
+  "sourcepath": "./demo/svelte/dist",
+  "outputfile": "./output.h",
+  "etag": "true",
+  "gzip": "true",
+  "cachetime": 0,
+  "created": false,
+  "version": "",
+  "espmethod": "initSvelteStaticFiles",
+  "define": "SVELTEESP32",
+  "exclude": ["*.map", "*.md", "test/**/*"]
+}
diff --git a/README.md b/README.md
@@ -12,6 +12,8 @@ In order to be able to easily update OTA, it is important - from the users' poin
 
 This npm package provides a solution for **inserting any JS client application into the ESP web server** (PsychicHttp and also ESPAsyncWebServer (https://github.com/ESP32Async/ESPAsyncWebServer) and ESP-IDF available, PsychicHttp is the default). For this, JS, html, css, font, assets, etc. files must be converted to binary byte array. Npm mode is easy to use and easy to **integrate into your CI/CD pipeline**.
 
+> Starting with version v1.12.0, you can use .rc file to config
+
 > Starting with version v1.11.0, you can exclude files by pattern
 
 > Starting with version v1.10.0, we reduced npm dependencies
@@ -427,8 +429,117 @@ You can use the following c++ directives at the project level if you want to con
 | `--version`   | Include a version string in generated header, e.g. `--version=v$npm_package_version` | ''                      |
 | `--espmethod` | Name of generated initialization method                                              | `initSvelteStaticFiles` |
 | `--define`    | Prefix of c++ defines (e.g., SVELTEESP32_COUNT)                                      | `SVELTEESP32`           |
+| `--config`    | Use custom RC file path                                                              | `.svelteesp32rc.json`   |
 | `-h`          | Show help                                                                            |                         |
 
+### Configuration File
+
+You can store frequently-used options in a configuration file to avoid repeating command line arguments. This is especially useful for CI/CD pipelines and team collaboration.
+
+#### Quick Start
+
+Create `.svelteesp32rc.json` in your project directory:
+
+```json
+{
+  "engine": "psychic",
+  "sourcepath": "./dist",
+  "outputfile": "./esp32/include/svelteesp32.h",
+  "etag": "true",
+  "gzip": "true",
+  "cachetime": 86400,
+  "exclude": ["*.map", "*.md"]
+}
+```
+
+Then simply run:
+
+```bash
+npx svelteesp32
+```
+
+No command line arguments needed!
+
+#### Search Locations
+
+The tool automatically searches for `.svelteesp32rc.json` in:
+
+1. Current working directory
+2. User home directory
+
+Or specify a custom location:
+
+```bash
+npx svelteesp32 --config=.svelteesp32rc.prod.json
+```
+
+#### Configuration Reference
+
+All CLI options can be specified in the RC file using long-form property names:
+
+| RC Property  | CLI Flag      | Type    | Example                                          |
+| ------------ | ------------- | ------- | ------------------------------------------------ |
+| `engine`     | `-e`          | string  | `"psychic"`, `"psychic2"`, `"async"`, `"espidf"` |
+| `sourcepath` | `-s`          | string  | `"./dist"`                                       |
+| `outputfile` | `-o`          | string  | `"./output.h"`                                   |
+| `etag`       | `--etag`      | string  | `"true"`, `"false"`, `"compiler"`                |
+| `gzip`       | `--gzip`      | string  | `"true"`, `"false"`, `"compiler"`                |
+| `cachetime`  | `--cachetime` | number  | `86400`                                          |
+| `created`    | `--created`   | boolean | `true`, `false`                                  |
+| `version`    | `--version`   | string  | `"v1.0.0"`                                       |
+| `espmethod`  | `--espmethod` | string  | `"initSvelteStaticFiles"`                        |
+| `define`     | `--define`    | string  | `"SVELTEESP32"`                                  |
+| `exclude`    | `--exclude`   | array   | `["*.map", "*.md"]`                              |
+
+#### CLI Override
+
+Command line arguments always take precedence over RC file values:
+
+```bash
+# Use RC settings but override etag
+npx svelteesp32 --etag=false
+
+# Use RC settings but add different exclude pattern
+npx svelteesp32 --exclude="*.txt"
+```
+
+#### Multiple Environments
+
+Create different config files for different environments:
+
+```bash
+# Development build
+npx svelteesp32 --config=.svelteesp32rc.dev.json
+
+# Production build
+npx svelteesp32 --config=.svelteesp32rc.prod.json
+```
+
+#### Exclude Pattern Behavior
+
+**Replace mode**: When you specify `exclude` patterns in RC file or CLI, they completely replace the defaults.
+
+- **No exclude specified**: Uses default system exclusions (`.DS_Store`, `Thumbs.db`, `.git`, etc.)
+- **RC file has exclude**: Replaces defaults with RC patterns
+- **CLI has --exclude**: Replaces RC patterns (or defaults if no RC)
+
+Example:
+
+```json
+// .svelteesp32rc.json
+{ "exclude": ["*.map"] }
+```
+
+Result: Only `*.map` is excluded (default patterns are replaced)
+
+To keep defaults, explicitly list them in your RC file:
+
+```json
+{
+  "exclude": [".DS_Store", "Thumbs.db", ".git", "*.map", "*.md"]
+}
+```
+
 ### Q&A
 
 - **How big a frontend application can be placed?** If you compress the content with gzip, even a 3-4Mb assets directory can be placed. This is a serious enough amount to serve a complete application.
diff --git a/src/commandLine.ts b/src/commandLine.ts
@@ -1,4 +1,8 @@
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+import { cyanLog, yellowLog } from './consoleColor';
 
 interface ICopyFilesArguments {
   engine: 'psychic' | 'psychic2' | 'async' | 'espidf';
@@ -15,10 +19,27 @@ interface ICopyFilesArguments {
   help?: boolean;
 }
 
+interface IRcFileConfig {
+  engine?: 'psychic' | 'psychic2' | 'async' | 'espidf';
+  sourcepath?: string;
+  outputfile?: string;
+  espmethod?: string;
+  define?: string;
+  gzip?: 'true' | 'false' | 'compiler';
+  etag?: 'true' | 'false' | 'compiler';
+  cachetime?: number;
+  created?: boolean;
+  version?: string;
+  exclude?: string[];
+}
+
 function showHelp(): never {
   console.log(`
 svelteesp32 - Svelte JS to ESP32 converter
 
+Configuration:
+  --config <path>            Use custom RC file (default: search for .svelteesp32rc.json)
+
 Options:
   -e, --engine <value>       The engine for which the include file is created
                              (psychic|psychic2|async|espidf) (default: "psychic")
@@ -34,6 +55,23 @@ Options:
   --exclude <pattern>        Exclude files matching glob pattern (repeatable or comma-separated)
                              Examples: --exclude="*.map" --exclude="test/**/*.ts"
   -h, --help                 Shows this help
+
+RC File:
+  The tool searches for .svelteesp32rc.json in:
+    1. Current directory (./.svelteesp32rc.json)
+    2. User home directory (~/.svelteesp32rc.json)
+
+  Example RC file (all fields optional):
+    {
+      "engine": "psychic",
+      "sourcepath": "./dist",
+      "outputfile": "./output.h",
+      "etag": "true",
+      "gzip": "true",
+      "exclude": ["*.map", "*.md"]
+    }
+
+  CLI arguments override RC file values.
 `);
   process.exit(0);
 }
@@ -61,8 +99,110 @@ const DEFAULT_EXCLUDE_PATTERNS = [
   '.gitattributes' // Git attributes file
 ];
 
+function findRcFile(customConfigPath?: string): string | undefined {
+  // If --config specified, use that exclusively
+  if (customConfigPath) {
+    if (existsSync(customConfigPath)) return customConfigPath;
+    throw new Error(`Config file not found: ${customConfigPath}`);
+  }
+
+  // Check current directory
+  for (const filename of ['.svelteesp32rc.json', '.svelteesp32rc']) {
+    const cwdPath = path.join(process.cwd(), filename);
+    if (existsSync(cwdPath)) return cwdPath;
+  }
+
+  // Check home directory
+  const homeDirectory = homedir();
+  for (const filename of ['.svelteesp32rc.json', '.svelteesp32rc']) {
+    const homePath = path.join(homeDirectory, filename);
+    if (existsSync(homePath)) return homePath;
+  }
+
+  return undefined;
+}
+
+function loadRcFile(rcPath: string): IRcFileConfig {
+  try {
+    const content = readFileSync(rcPath, 'utf8');
+    const config = JSON.parse(content);
+    return validateRcConfig(config, rcPath);
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new Error(`Invalid JSON in RC file ${rcPath}: ${error.message}`);
+
+    throw error;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function validateRcConfig(config: any, rcPath: string): IRcFileConfig {
+  if (typeof config !== 'object' || config === null) throw new Error(`RC file ${rcPath} must contain a JSON object`);
+
+  const validKeys = new Set([
+    'engine',
+    'sourcepath',
+    'outputfile',
+    'espmethod',
+    'define',
+    'gzip',
+    'etag',
+    'cachetime',
+    'created',
+    'version',
+    'exclude'
+  ]);
+
+  // Warn about unknown keys
+  for (const key of Object.keys(config))
+    if (!validKeys.has(key)) console.warn(yellowLog(`Warning: Unknown property '${key}' in RC file ${rcPath}`));
+
+  // Validate individual properties
+  if (config.engine !== undefined) config.engine = validateEngine(config.engine);
+
+  if (config.etag !== undefined) config.etag = validateTriState(config.etag, 'etag');
+
+  if (config.gzip !== undefined) config.gzip = validateTriState(config.gzip, 'gzip');
+
+  if (config.cachetime !== undefined && (typeof config.cachetime !== 'number' || Number.isNaN(config.cachetime)))
+    throw new TypeError(`Invalid cachetime in RC file: ${config.cachetime}`);
+
+  if (config.exclude !== undefined) {
+    if (!Array.isArray(config.exclude)) throw new TypeError("'exclude' in RC file must be an array");
+
+    // Validate each exclude pattern is a string
+    for (const pattern of config.exclude)
+      if (typeof pattern !== 'string') throw new TypeError('All exclude patterns must be strings');
+  }
+
+  return config;
+}
+
 function parseArguments(): ICopyFilesArguments {
   const arguments_ = process.argv.slice(2);
+
+  // STEP 1: Check for --config flag first
+  let customConfigPath: string | undefined;
+  for (let index = 0; index < arguments_.length; index++) {
+    const argument = arguments_[index];
+    if (!argument) continue;
+
+    if (argument === '--config' && arguments_[index + 1]) {
+      customConfigPath = arguments_[index + 1];
+      break;
+    }
+    if (argument.startsWith('--config=')) {
+      customConfigPath = argument.slice('--config='.length);
+      break;
+    }
+  }
+
+  // STEP 2: Find and load RC file
+  const rcPath = findRcFile(customConfigPath);
+  const rcConfig = rcPath ? loadRcFile(rcPath) : {};
+
+  if (rcPath) console.log(cyanLog(`[SvelteESP32] Using config from: ${rcPath}`));
+
+  // STEP 3: Initialize with defaults
   const result: Partial<ICopyFilesArguments> = {
     engine: 'psychic',
     outputfile: 'svelteesp32.h',
@@ -76,6 +216,24 @@ function parseArguments(): ICopyFilesArguments {
     exclude: [...DEFAULT_EXCLUDE_PATTERNS]
   };
 
+  // STEP 4: Merge RC file values
+  if (rcConfig.engine) result.engine = rcConfig.engine;
+  if (rcConfig.sourcepath) result.sourcepath = rcConfig.sourcepath;
+  if (rcConfig.outputfile) result.outputfile = rcConfig.outputfile;
+  if (rcConfig.etag) result.etag = rcConfig.etag;
+  if (rcConfig.gzip) result.gzip = rcConfig.gzip;
+  if (rcConfig.cachetime !== undefined) result.cachetime = rcConfig.cachetime;
+  if (rcConfig.created !== undefined) result.created = rcConfig.created;
+  if (rcConfig.version) result.version = rcConfig.version;
+  if (rcConfig.espmethod) result.espmethod = rcConfig.espmethod;
+  if (rcConfig.define) result.define = rcConfig.define;
+
+  // Replace defaults with RC exclude if provided
+  if (rcConfig.exclude && rcConfig.exclude.length > 0) result.exclude = [...rcConfig.exclude];
+
+  // STEP 5: Parse CLI arguments
+  const cliExclude: string[] = [];
+
   for (let index = 0; index < arguments_.length; index++) {
     const argument = arguments_[index];
 
@@ -95,6 +253,9 @@ function parseArguments(): ICopyFilesArguments {
       const flagName = flag.slice(2);
 
       switch (flagName) {
+        case 'config':
+          // Already processed, skip
+          break;
         case 'engine':
           result.engine = validateEngine(value);
           break;
@@ -129,8 +290,7 @@ function parseArguments(): ICopyFilesArguments {
             .split(',')
             .map((p) => p.trim())
             .filter(Boolean);
-          result.exclude = result.exclude || [...DEFAULT_EXCLUDE_PATTERNS];
-          result.exclude.push(...patterns);
+          cliExclude.push(...patterns);
           break;
         }
         default:
@@ -179,6 +339,10 @@ function parseArguments(): ICopyFilesArguments {
       if (!nextArgument || nextArgument.startsWith('-')) throw new Error(`Missing value for flag: ${argument}`);
 
       switch (flag) {
+        case 'config':
+          // Already processed, skip
+          index++;
+          break;
         case 'engine':
           result.engine = validateEngine(nextArgument);
           index++;
@@ -222,8 +386,7 @@ function parseArguments(): ICopyFilesArguments {
             .split(',')
             .map((p) => p.trim())
             .filter(Boolean);
-          result.exclude = result.exclude || [...DEFAULT_EXCLUDE_PATTERNS];
-          result.exclude.push(...patterns);
+          cliExclude.push(...patterns);
           index++;
           break;
         }
@@ -236,9 +399,12 @@ function parseArguments(): ICopyFilesArguments {
     throw new Error(`Unknown argument: ${argument}`);
   }
 
-  // Validate required arguments
+  // STEP 6: Apply CLI exclude (replaces RC/defaults)
+  if (cliExclude.length > 0) result.exclude = [...cliExclude];
+
+  // STEP 7: Validate required arguments
   if (!result.sourcepath) {
-    console.error('Error: --sourcepath is required');
+    console.error('Error: --sourcepath is required (can be specified in RC file or CLI)');
     showHelp();
   }
 
diff --git a/test/unit/commandLine.test.ts b/test/unit/commandLine.test.ts
