@fonoster/common 0.27.0 → 0.31.0

package/dist/config/interpolateEnv.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+type Env = Record<string, string | undefined>;
+type InterpolateOptions = {
+    /**
+     * Key paths where `${VAR}` may appear, e.g. `database.url` or `nats.*`
+     * (`*` matches the key and everything below it; `*` alone matches every key). When given,
+     * `${...}` at any other path is an error. When omitted, every string is interpolated.
+     */
+    allowedPaths?: string[];
+};
+/**
+ * Recursively walks an already-parsed config value and interpolates `${VAR}`
+ * references in its strings. Returns a new value; the input is not mutated.
+ * Errors name the key path where they happened.
+ */
+declare function interpolateEnv<T>(input: T, env?: Env, options?: InterpolateOptions): T;
+export { interpolateEnv, InterpolateOptions };

package/dist/config/interpolateEnv.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interpolateEnv = interpolateEnv;
+/**
+ * Shell / docker-compose style variable interpolation for config files.
+ *
+ * Supported forms inside any string value:
+ *   - `${VAR}`          -> value of VAR; throws if VAR is unset or empty
+ *   - `${VAR:-default}` -> value of VAR, or `default` when VAR is unset or empty
+ *
+ * Anything that is not a `${...}` reference is left untouched, so plain literals
+ * (`http://asterisk:8088`, `$5.00`, ...) pass through unchanged. Services limit
+ * it to values shared with other containers (see `allowedPaths`), so each value
+ * is written once.
+ */
+const VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(:-([^}]*))?\}/g;
+function interpolateString(value, env) {
+    return value.replace(VAR_PATTERN, (_match, name, hasDefault, fallback) => {
+        const current = env[name];
+        if (current !== undefined && current !== "") {
+            return current;
+        }
+        if (hasDefault !== undefined) {
+            return fallback;
+        }
+        throw new Error(`references undefined environment variable \${${name}} and no default was given`);
+    });
+}
+const HAS_REFERENCE = /\$\{[^}]*\}/;
+function isAllowed(path, allowedPaths) {
+    return allowedPaths.some((pattern) => pattern === "*"
+        ? true
+        : pattern.endsWith(".*")
+            ? path === pattern.slice(0, -2) ||
+                path.startsWith(`${pattern.slice(0, -2)}.`)
+            : path === pattern);
+}
+function walk(input, env, options, path) {
+    if (typeof input === "string") {
+        if (!HAS_REFERENCE.test(input)) {
+            return input;
+        }
+        const where = path || "(root)";
+        if (options.allowedPaths && !isAllowed(path, options.allowedPaths)) {
+            throw new Error(`${where}: \${...} is only allowed for values shared with other containers (${options.allowedPaths.join(", ") || "none here"})`);
+        }
+        try {
+            return interpolateString(input, env);
+        }
+        catch (e) {
+            throw new Error(`${where}: ${e.message}`);
+        }
+    }
+    if (Array.isArray(input)) {
+        return input.map((item, index) => walk(item, env, options, `${path}[${index}]`));
+    }
+    if (input !== null && typeof input === "object") {
+        const entries = Object.entries(input).map(([key, value]) => [key, walk(value, env, options, path ? `${path}.${key}` : key)]);
+        return Object.fromEntries(entries);
+    }
+    return input;
+}
+/**
+ * Recursively walks an already-parsed config value and interpolates `${VAR}`
+ * references in its strings. Returns a new value; the input is not mutated.
+ * Errors name the key path where they happened.
+ */
+function interpolateEnv(input, env = process.env, options = {}) {
+    return walk(input, env, options, "");
+}

package/dist/config/loadServiceConfig.d.ts

@@ -0,0 +1,28 @@
+import { z, ZodTypeAny } from "zod";
+type Env = Record<string, string | undefined>;
+type LoadServiceConfigOptions<S extends ZodTypeAny> = {
+    /** Service name, used in messages. */
+    service: string;
+    /** File name without extension. Defaults to `service`. */
+    fileBase?: string;
+    /** Zod schema that validates (and applies defaults to) the config. */
+    schema: S;
+    /** Defaults to `process.argv`; `--config <path>` picks the file. */
+    argv?: string[];
+    /** Only used to resolve `${VAR}` placeholders. Defaults to `process.env`. */
+    env?: Env;
+    /** Directories searched when `--config` is absent. */
+    searchDirs?: string[];
+    /**
+     * Key paths that may reference `${VAR}` (values Compose passes from `.env`). `["*"]` allows
+     * every key (the default for Fonoster services, unify-config-placeholders); `${...}` anywhere
+     * else is an error.
+     */
+    interpolatePaths?: string[];
+};
+/**
+ * Loads, interpolates and strictly validates a service's config file.
+ * Throws with the file path and the offending key path on any problem.
+ */
+declare function loadServiceConfig<S extends ZodTypeAny>(options: LoadServiceConfigOptions<S>): z.output<S>;
+export { loadServiceConfig, LoadServiceConfigOptions };

package/dist/config/loadServiceConfig.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadServiceConfig = loadServiceConfig;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const fs_1 = require("fs");
+const logger_1 = require("@fonoster/logger");
+const interpolateEnv_1 = require("./interpolateEnv");
+const parseConfigFile_1 = require("./parseConfigFile");
+const resolveConfigFile_1 = require("./resolveConfigFile");
+const resolveSecretRefs_1 = require("./resolveSecretRefs");
+const strictDeep_1 = require("./strictDeep");
+const logger = (0, logger_1.getLogger)({ service: "common", filePath: __filename });
+/**
+ * One line per problem, each led by the key path:
+ * `smtp: unknown key "hsot"`, `features.auth.methods[1]: Invalid enum value ...`.
+ */
+function formatIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path
+            .map((segment, index) => typeof segment === "number"
+            ? `[${segment}]`
+            : index === 0
+                ? segment
+                : `.${segment}`)
+            .join("");
+        const where = path || "(root)";
+        if (issue.code === "unrecognized_keys") {
+            const keys = issue.keys.map((key) => `"${key}"`).join(", ");
+            return `${where}: unknown key${issue.keys.length > 1 ? "s" : ""} ${keys}`;
+        }
+        return `${where}: ${issue.message}`;
+    })
+        .join("; ");
+}
+/**
+ * Loads, interpolates and strictly validates a service's config file.
+ * Throws with the file path and the offending key path on any problem.
+ */
+function loadServiceConfig(options) {
+    var _a, _b, _c, _d, _e;
+    const { service, schema } = options;
+    const fileBase = (_a = options.fileBase) !== null && _a !== void 0 ? _a : service;
+    const argv = (_b = options.argv) !== null && _b !== void 0 ? _b : process.argv;
+    const env = (_c = options.env) !== null && _c !== void 0 ? _c : process.env;
+    const resolved = (0, resolveConfigFile_1.resolveConfigFile)(fileBase, argv, options.searchDirs);
+    const where = (_d = resolved.path) !== null && _d !== void 0 ? _d : "(built-in defaults)";
+    let raw = {};
+    if ("searched" in resolved) {
+        logger.warn(`no ${service} config file found (looked for ${resolved.searched.join(", ")}); using built-in defaults`);
+    }
+    else if (!(0, fs_1.existsSync)(resolved.path)) {
+        throw new Error(`unable to read ${service} config at ${resolved.path}: file not found`);
+    }
+    else {
+        try {
+            raw = (0, parseConfigFile_1.parseConfigFile)(resolved.path, (0, fs_1.readFileSync)(resolved.path, "utf8"));
+        }
+        catch (e) {
+            throw new Error(`unable to read ${service} config at ${resolved.path}: ${e.message}`);
+        }
+    }
+    // "$schema" points editors at the JSON Schema for autocomplete; it isn't config.
+    if (raw !== null && typeof raw === "object" && "$schema" in raw) {
+        const rest = Object.assign({}, raw);
+        delete rest.$schema;
+        raw = rest;
+    }
+    let interpolated;
+    try {
+        interpolated = (0, interpolateEnv_1.interpolateEnv)(raw, env, {
+            allowedPaths: (_e = options.interpolatePaths) !== null && _e !== void 0 ? _e : []
+        });
+    }
+    catch (e) {
+        throw new Error(`invalid ${service} config at ${where}: ${e.message}`);
+    }
+    // `secret://` references (D8): resolved here so the schema sees real values.
+    let withSecrets;
+    try {
+        withSecrets = (0, resolveSecretRefs_1.resolveSecretRefs)(interpolated, { env });
+    }
+    catch (e) {
+        throw new Error(`invalid ${service} config at ${where}: ${e.message}`);
+    }
+    const strictSchema = (0, strictDeep_1.strictDeep)(schema);
+    const result = strictSchema.safeParse(withSecrets);
+    if (!result.success) {
+        throw new Error(`invalid ${service} config at ${where}: ${formatIssues(result.error)}`);
+    }
+    if (resolved.path) {
+        logger.verbose(`loaded ${service} config`, { path: resolved.path });
+    }
+    return result.data;
+}

package/dist/config/logsSchema.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from "zod";
+/** The `logs` section shared by every Fonoster service's config file. */
+declare const logsSchema: z.ZodDefault<z.ZodEffects<z.ZodObject<{
+    level: z.ZodDefault<z.ZodEnum<["error", "warn", "info", "http", "verbose", "debug", "silly"]>>;
+    format: z.ZodDefault<z.ZodEnum<["json", "text"]>>;
+    transport: z.ZodDefault<z.ZodEnum<["console", "fluent"]>>;
+    fluent: z.ZodOptional<z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodDefault<z.ZodNumber>;
+        tagPrefix: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    }, {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    format?: "text" | "json";
+    level?: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+    fluent?: {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    };
+    transport?: "console" | "fluent";
+}, {
+    format?: "text" | "json";
+    level?: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+    fluent?: {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    };
+    transport?: "console" | "fluent";
+}>, {
+    format?: "text" | "json";
+    level?: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+    fluent?: {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    };
+    transport?: "console" | "fluent";
+}, {
+    format?: "text" | "json";
+    level?: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+    fluent?: {
+        host?: string;
+        port?: number;
+        tagPrefix?: string;
+    };
+    transport?: "console" | "fluent";
+}>>;
+type LogsConfig = z.infer<typeof logsSchema>;
+export { logsSchema, LogsConfig };

package/dist/config/logsSchema.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logsSchema = void 0;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const zod_1 = require("zod");
+/** The `logs` section shared by every Fonoster service's config file. */
+const logsSchema = zod_1.z
+    .object({
+    level: zod_1.z
+        .enum(["error", "warn", "info", "http", "verbose", "debug", "silly"])
+        .default("info"),
+    format: zod_1.z.enum(["json", "text"]).default("json"),
+    transport: zod_1.z.enum(["console", "fluent"]).default("console"),
+    fluent: zod_1.z
+        .object({
+        host: zod_1.z.string(),
+        port: zod_1.z.number().int().positive().default(24224),
+        tagPrefix: zod_1.z.string().default("fonoster-logs")
+    })
+        .optional()
+})
+    .superRefine((logs, ctx) => {
+    if (logs.transport === "fluent" && !logs.fluent) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["fluent"],
+            message: "required when transport is fluent"
+        });
+    }
+})
+    .default({});
+exports.logsSchema = logsSchema;

package/dist/config/natsConnection.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from "zod";
+/**
+ * A service's NATS connection settings (add-platform 4.1): the URL plus, when the server has
+ * per-service users, the service's user and password. The password is usually a `secret://`
+ * reference, resolved by the config loader like any other value.
+ */
+export declare const natsConnectionSchema: z.ZodObject<{
+    url: z.ZodString;
+    user: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    url?: string;
+    user?: string;
+    password?: string;
+}, {
+    url?: string;
+    user?: string;
+    password?: string;
+}>;
+export type NatsConnectionConfig = z.infer<typeof natsConnectionSchema>;
+/** A NATS URL or full connection settings. */
+export type NatsTarget = string | NatsConnectionConfig;
+/**
+ * The inbox prefix of a NATS user: replies to its requests (and JetStream deliveries) arrive
+ * under `_INBOX_<user>.`, the only inbox its permissions let it subscribe to, so no service can
+ * read another's replies (nats-permissions/*.conf).
+ */
+export declare function natsInboxPrefix(user: string): string;
+/** nats.js `connect` options for a URL or a `{ url, user, password }` setting. */
+export declare function natsConnectOptions(nats: NatsTarget): {
+    servers: string;
+    user?: string;
+    pass?: string;
+    inboxPrefix?: string;
+};

package/dist/config/natsConnection.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.natsConnectionSchema = void 0;
+exports.natsInboxPrefix = natsInboxPrefix;
+exports.natsConnectOptions = natsConnectOptions;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const zod_1 = require("zod");
+/**
+ * A service's NATS connection settings (add-platform 4.1): the URL plus, when the server has
+ * per-service users, the service's user and password. The password is usually a `secret://`
+ * reference, resolved by the config loader like any other value.
+ */
+exports.natsConnectionSchema = zod_1.z
+    .object({
+    url: zod_1.z.string().min(1),
+    user: zod_1.z.string().min(1).optional(),
+    password: zod_1.z.string().min(1).optional()
+})
+    .strict();
+/**
+ * The inbox prefix of a NATS user: replies to its requests (and JetStream deliveries) arrive
+ * under `_INBOX_<user>.`, the only inbox its permissions let it subscribe to, so no service can
+ * read another's replies (nats-permissions/*.conf).
+ */
+function natsInboxPrefix(user) {
+    return `_INBOX_${user}`;
+}
+/** nats.js `connect` options for a URL or a `{ url, user, password }` setting. */
+function natsConnectOptions(nats) {
+    var _a;
+    if (typeof nats === "string")
+        return { servers: nats };
+    return nats.user
+        ? {
+            servers: nats.url,
+            user: nats.user,
+            pass: (_a = nats.password) !== null && _a !== void 0 ? _a : "",
+            inboxPrefix: natsInboxPrefix(nats.user)
+        }
+        : { servers: nats.url };
+}

package/dist/config/parseConfigFile.d.ts

@@ -0,0 +1,7 @@
+declare const CONFIG_EXTENSIONS: string[];
+/**
+ * Parses a config file's text. The extension picks the format: `.yaml`/`.yml`
+ * as YAML, `.json`/`.jsonc` as JSON with comments and trailing commas.
+ */
+declare function parseConfigFile(path: string, text: string): unknown;
+export { parseConfigFile, CONFIG_EXTENSIONS };

package/dist/config/parseConfigFile.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_EXTENSIONS = void 0;
+exports.parseConfigFile = parseConfigFile;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const path_1 = require("path");
+const jsonc_parser_1 = require("jsonc-parser");
+const yaml_1 = require("yaml");
+const YAML_EXTENSIONS = [".yaml", ".yml"];
+const JSON_EXTENSIONS = [".json", ".jsonc"];
+const CONFIG_EXTENSIONS = [...YAML_EXTENSIONS, ...JSON_EXTENSIONS];
+exports.CONFIG_EXTENSIONS = CONFIG_EXTENSIONS;
+function lineAndColumn(text, offset) {
+    const before = text.slice(0, offset);
+    const line = before.split("\n").length;
+    const column = offset - before.lastIndexOf("\n");
+    return { line, column };
+}
+/**
+ * Parses a config file's text. The extension picks the format: `.yaml`/`.yml`
+ * as YAML, `.json`/`.jsonc` as JSON with comments and trailing commas.
+ */
+function parseConfigFile(path, text) {
+    var _a;
+    const extension = (0, path_1.extname)(path).toLowerCase();
+    if (YAML_EXTENSIONS.includes(extension)) {
+        return (_a = (0, yaml_1.parse)(text)) !== null && _a !== void 0 ? _a : {};
+    }
+    if (JSON_EXTENSIONS.includes(extension)) {
+        const errors = [];
+        const value = (0, jsonc_parser_1.parse)(text, errors, {
+            allowTrailingComma: true,
+            disallowComments: false
+        });
+        if (errors.length > 0) {
+            const first = errors[0];
+            const { line, column } = lineAndColumn(text, first.offset);
+            throw new Error(`${(0, jsonc_parser_1.printParseErrorCode)(first.error)} at line ${line}, column ${column}`);
+        }
+        return value !== null && value !== void 0 ? value : {};
+    }
+    throw new Error(`unsupported extension "${extension}" (use ${CONFIG_EXTENSIONS.join(", ")})`);
+}

package/dist/config/resolveConfigFile.d.ts

@@ -0,0 +1,17 @@
+declare const DEFAULT_SEARCH_DIRS: string[];
+type ResolvedConfigFile = {
+    path: string;
+    explicit: boolean;
+} | {
+    path: undefined;
+    explicit: false;
+    searched: string[];
+};
+/**
+ * Finds a service's config file. `--config <path>` wins; otherwise each search
+ * directory is tried in order for `<fileBase>` with a supported extension.
+ * Two candidates in the same directory is an error: the operator would not
+ * know which one is in effect.
+ */
+declare function resolveConfigFile(fileBase: string, argv: string[], searchDirs?: string[]): ResolvedConfigFile;
+export { resolveConfigFile, DEFAULT_SEARCH_DIRS, ResolvedConfigFile };

package/dist/config/resolveConfigFile.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SEARCH_DIRS = void 0;
+exports.resolveConfigFile = resolveConfigFile;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const parseConfigFile_1 = require("./parseConfigFile");
+// `/config` is where the bundle mounts each service's file (unify-config-placeholders).
+const DEFAULT_SEARCH_DIRS = ["/config", "/opt/fonoster", "./config"];
+exports.DEFAULT_SEARCH_DIRS = DEFAULT_SEARCH_DIRS;
+/**
+ * Finds a service's config file. `--config <path>` wins; otherwise each search
+ * directory is tried in order for `<fileBase>` with a supported extension.
+ * Two candidates in the same directory is an error: the operator would not
+ * know which one is in effect.
+ */
+function resolveConfigFile(fileBase, argv, searchDirs = DEFAULT_SEARCH_DIRS) {
+    const flagIndex = argv.indexOf("--config");
+    const fromFlag = flagIndex >= 0 ? argv[flagIndex + 1] : undefined;
+    if (fromFlag) {
+        return { path: (0, path_1.resolve)(process.cwd(), fromFlag), explicit: true };
+    }
+    const searched = [];
+    for (const dir of searchDirs) {
+        const candidates = parseConfigFile_1.CONFIG_EXTENSIONS.map((extension) => (0, path_1.resolve)(process.cwd(), (0, path_1.join)(dir, `${fileBase}${extension}`)));
+        searched.push(...candidates);
+        const found = candidates.filter((candidate) => (0, fs_1.existsSync)(candidate));
+        if (found.length > 1) {
+            throw new Error(`found more than one ${fileBase} config file (${found.join(", ")}); keep only one`);
+        }
+        if (found.length === 1) {
+            return { path: found[0], explicit: false };
+        }
+    }
+    return { path: undefined, explicit: false, searched };
+}

package/dist/config/resolveSecretRefs.d.ts

@@ -0,0 +1,35 @@
+type Env = Record<string, string | undefined>;
+/**
+ * `secret://` references in config values (add-platform, decision D8). A string value that is
+ * exactly a reference is replaced at startup by the secret it names, so YAML never holds the raw
+ * secret:
+ *
+ *   secret://env/NAME                 the environment variable NAME
+ *   secret://file/<absolute path>     a file's contents (e.g. secret://file/run/secrets/db-url)
+ *   secret://k8s/<secret>#<key>       a Kubernetes Secret mounted as a volume, read from
+ *   secret://k8s/<ns>/<secret>#<key>  <FONOSTER_SECRETS_DIR>/<secret>/<key>
+ *                                     (default /var/run/fonoster/secrets; the Helm chart mounts
+ *                                     every referenced Secret there). The namespace, when given,
+ *                                     must be the pod's (POD_NAMESPACE) if that is known.
+ *
+ * File contents lose one trailing newline. Errors name the key path and the reference, never a
+ * value. Values that only contain `secret://` somewhere else are left alone.
+ */
+export declare const SECRET_PREFIX = "secret://";
+export declare const DEFAULT_SECRETS_DIR = "/var/run/fonoster/secrets";
+export type SecretRefOptions = {
+    env?: Env;
+    /** Where Kubernetes Secrets are mounted (default FONOSTER_SECRETS_DIR or /var/run/fonoster/secrets). */
+    secretsDir?: string;
+    /** Reads a file (tests). */
+    readFile?: (path: string) => string;
+};
+export declare function isSecretRef(value: unknown): value is string;
+/** Resolves one `secret://` reference. Throws with a message that never contains the secret. */
+export declare function resolveSecretRef(ref: string, options?: SecretRefOptions): string;
+/**
+ * Returns a copy of a parsed config with every `secret://` value resolved. Errors name the key
+ * path (`providers.deepgram.credential.value: secret://env/DG: environment variable DG is not set`).
+ */
+export declare function resolveSecretRefs<T>(input: T, options?: SecretRefOptions): T;
+export {};