Read CLI and server options from env vars and a config file

[devin-ai-integration]

Summary

Refs #12

The CLI and osmsm serve can now take defaults from OSMSM_* env vars and from a JSON config file, with the precedence CLI flags > env vars > config file > built-in defaults. The library (src/lib.js) is untouched: it keeps using exactly the options passed to it.

New module src/config.js (added to the published files):

envVarName("tileserverUrl")            // "OSMSM_TILESERVER_URL"
loadConfigFile({ configPath, cwd, env })  // --config / $OSMSM_CONFIG (must exist) → ./osmsm.config.json → $XDG_CONFIG_HOME/osmsm/config.json
coerceValue(option, str)               // numbers / booleans (true|1|yes|on…) / scale = bool-or-JSON, error on bad values
readEnvOptions(keys, env)              // OSMSM_* first, then legacy PORT / HEADER_CHECK / HEADER_CHECK_FAIL_MESSAGE
resolveOptions({ keys, cli, env, config, defaults }) // → { values, sources }

src/cli.js uses commander's getOptionValueSource(key) === "cli" to separate explicitly passed flags from built-in defaults, so env/config values sit between them. It adds -C, --config <path> (global, also works as osmsm serve --config x), warns on stderr about unknown config keys, and exits with code 2 on a missing explicit config file or an uncoercible value.

osmsm serve gains --headerCheck <name:value> and --headerCheckFailMessage <string> (previously env-only), --port defaults to 3000 through the same resolution, and any render option coming from env/config is used as the default for every request (request params still win). To make this explicit and testable, src/server.js now exports:

export function createApp({ headerCheck = process.env.HEADER_CHECK, headerCheckFailMessage = process.env.HEADER_CHECK_FAIL_MESSAGE, defaults = {} } = {})
export default createServer(createApp());   // unchanged behaviour for existing importers

and the handler renders osmsm({ ...defaults, ...params }).

Docs: new "Configuration (CLI and server)" section in README (precedence, env var naming, file lookup order, server options table), CHANGELOG entry under "Unreleased".

Tests (npm test, 47 passing, no browser needed for the new ones): test/config.test.js (unit), test/cli.test.js (spawns the CLI with -D in a temp cwd / isolated env to check each layer and the precedence), test/server.test.js (createApp defaults, header check, request override).

Notes / decisions for the reviewer:

• Env var naming is OSMSM_ + upper snake case of the long option (OSMSM_MAX_ZOOM, OSMSM_GEOJSONFILE). Legacy PORT/HEADER_CHECK/HEADER_CHECK_FAIL_MESSAGE keep working, below the OSMSM_ ones.
• Config file is flat: render options and server options (port, headerCheck, headerCheckFailMessage) share the same object.
• Pre-existing, not touched here: the CLI calls process.exit(0) right after process.stdout.write(v), which truncates output at 64KB when stdout is a pipe (e.g. osmsm -D | grep). The CLI tests capture stdout through a file to avoid it; worth a separate fix (process.stdout.write(v, () => process.exit(0))).

Link to Devin session: https://app.devin.ai/sessions/d17c0e03ecff4994bf8d3f555c0547ba
Open in Devin Desktop: https://app.devin.ai/desktop/session/d17c0e03ecff4994bf8d3f555c0547ba?variant=devin
Requested by: @jperelli

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring