@andreas-timm/config 0.1.0 → 0.2.0

package/README.md

@@ -9,11 +9,12 @@ Bun-first utilities for loading layered TOML config files and validating the mer
 - Deep-merge files with later files overriding earlier values.
 - Inject `root_dir` before schema validation.
 - Report Zod validation issues with the resolved source file paths.
+- Post-process known string values such as `secret = "!pass show secret"` as command-backed secrets.
 
 ## Install
 
 ```sh
-bun add @andreas-timm/config zod
+pnpm add @andreas-timm/config zod
 ```
 
 ## Usage
@@ -49,5 +50,34 @@ export function resetConfig(): void {
 
 `loadConfig()` caches the promise in module scope, so files are read and parsed only on the first call and concurrent callers share the in-flight load. Call `resetConfig()` to force a reload in tests or after editing a TOML file.
 
+## Command-backed secrets
+
+Use command-backed values when an application should keep the secret in a password manager or external secret store, but still describe how to fetch it in TOML:
+
+```toml
+secret = "!pass show secret"
+literal = "!!starts-with-bang"
+```
+
+Post-process only the specific field that may contain a command:
+
+```ts
+import { load, resolveShellCommand } from "@andreas-timm/config";
+
+const config = await load(ConfigSchema, rootDir, configFiles);
+const secret = await resolveShellCommand(config.secret, { cwd: rootDir });
+```
+
+This keeps loading as plain TOML/Zod validation and makes command execution an application-level decision. The config schema should validate the placeholder as a string, and the application should validate or use the resolved secret at the point where it is needed.
+
+You can also write the resolved value back into your application config object:
+
+```ts
+const config = await load(ConfigSchema, rootDir, configFiles);
+config.secret = await resolveShellCommand(config.secret, { cwd: rootDir });
+```
+
+By default, command resolution uses `!` as the prefix, `!!` as a literal escape, strips one final newline from command output, applies a 10 second timeout, and rejects stdout or stderr above 16 KiB. Treat any value passed to `resolveShellCommand()` as trusted executable input.
+
 For the full setup pattern and usage guidance, see [`skills/bun-config/SKILL.md`](https://github.com/andreas-timm/config-ts/blob/main/skills/bun-config/SKILL.md).
 

package/dist/config.d.ts

@@ -0,0 +1 @@
+export declare function resolveConfigFilePath(rootDir: string, fileName: string): string;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-import { z } from "zod";
-export declare function load<Config>(configSchema: z.ZodType<Config>, rootDir: string, configFiles?: string[]): Promise<Config>;
+export { load } from "./load";
+export type { ResolveShellCommandOptions } from "./shell";
+export { resolveShellCommand } from "./shell";

package/dist/index.js

@@ -1,11 +1,13 @@
 // @bun
-// src/index.ts
-import { homedir } from "os";
-import { join } from "path";
+// src/load.ts
 import merge from "lodash.merge";
 import { concatMap, from, lastValueFrom } from "rxjs";
 import { reduce } from "rxjs/operators";
 import { z } from "zod";
+
+// src/config.ts
+import { homedir } from "os";
+import { join } from "path";
 function resolveConfigFilePath(rootDir, fileName) {
   if (fileName.startsWith("/")) {
     return fileName;
@@ -22,6 +24,8 @@ function resolveConfigFilePath(rootDir, fileName) {
   }
   return join(rootDir, fileName);
 }
+
+// src/load.ts
 async function load(configSchema, rootDir, configFiles = ["global.toml", "local.toml"]) {
   const config$ = from(configFiles).pipe(concatMap(async (fileName) => {
     const file = Bun.file(resolveConfigFilePath(rootDir, fileName));
@@ -57,6 +61,113 @@ ${details}`;
     throw err;
   }
 }
+// src/shell.ts
+var DEFAULT_SHELL_COMMAND_PREFIX = "!";
+var DEFAULT_SHELL_COMMAND_TIMEOUT_MS = 1e4;
+var DEFAULT_SHELL_COMMAND_MAX_OUTPUT_BYTES = 16 * 1024;
+function defaultShell() {
+  if (process.platform === "win32") {
+    return ["cmd.exe", "/d", "/s", "/c"];
+  }
+  return ["/bin/sh", "-c"];
+}
+function stripFinalNewline(value) {
+  return value.replace(/\r?\n$/u, "");
+}
+function shellCommandValueError(message) {
+  return new Error(`Shell command config value ${message}`);
+}
+function getCommand(value, prefix) {
+  if (!value.startsWith(prefix) || value.startsWith(prefix + prefix)) {
+    return;
+  }
+  const command = value.slice(prefix.length).trimStart();
+  if (command.length === 0) {
+    throw shellCommandValueError("is empty");
+  }
+  return command;
+}
+function getLiteralValue(value, prefix) {
+  if (value.startsWith(prefix + prefix)) {
+    return value.slice(prefix.length);
+  }
+  return value;
+}
+async function readLimitedText(stream, maxBytes) {
+  const reader = stream.getReader();
+  const chunks = [];
+  let size = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    size += value.byteLength;
+    if (size > maxBytes) {
+      throw shellCommandValueError(`produced more than ${maxBytes} bytes`);
+    }
+    chunks.push(value);
+  }
+  const output = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    output.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(output);
+}
+async function runShellCommand(command, options = {}) {
+  const proc = Bun.spawn({
+    cmd: [...options.shell ?? defaultShell(), command],
+    cwd: options.cwd,
+    env: options.env,
+    stderr: "pipe",
+    stdin: null,
+    stdout: "pipe",
+    timeout: options.timeoutMs ?? DEFAULT_SHELL_COMMAND_TIMEOUT_MS
+  });
+  const stdout = readLimitedText(proc.stdout, options.maxOutputBytes ?? DEFAULT_SHELL_COMMAND_MAX_OUTPUT_BYTES);
+  const stderr = readLimitedText(proc.stderr, options.maxOutputBytes ?? DEFAULT_SHELL_COMMAND_MAX_OUTPUT_BYTES);
+  try {
+    const [output, errorOutput, exitCode] = await Promise.all([
+      stdout,
+      stderr,
+      proc.exited
+    ]);
+    return {
+      errorOutput,
+      exitCode,
+      output,
+      signalCode: proc.signalCode ?? undefined
+    };
+  } catch (err) {
+    proc.kill();
+    await Promise.allSettled([stdout, stderr, proc.exited]);
+    throw err;
+  }
+}
+function assertSuccessfulCommand(result, options) {
+  if (result.exitCode === 0) {
+    return;
+  }
+  const status = result.exitCode === null && result.signalCode ? `terminated by signal ${result.signalCode}` : `failed with exit code ${result.exitCode}`;
+  const stderrDetails = options.includeStderrInErrors && result.errorOutput.trim().length > 0 ? `: ${result.errorOutput.trim()}` : "";
+  throw shellCommandValueError(`${status}${stderrDetails}`);
+}
+async function resolveShellCommand(value, options = {}) {
+  const prefix = options.prefix ?? DEFAULT_SHELL_COMMAND_PREFIX;
+  if (prefix.length === 0) {
+    throw new Error("Shell command prefix must not be empty");
+  }
+  const command = getCommand(value, prefix);
+  if (!command) {
+    return getLiteralValue(value, prefix);
+  }
+  const result = await runShellCommand(command, options);
+  assertSuccessfulCommand(result, options);
+  return options.stripFinalNewline ?? true ? stripFinalNewline(result.output) : result.output;
+}
 export {
+  resolveShellCommand,
   load
 };

package/dist/load.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export declare function load<Config>(configSchema: z.ZodType<Config>, rootDir: string, configFiles?: string[]): Promise<Config>;

package/dist/shell.d.ts

@@ -0,0 +1,13 @@
+type ShellCommandEnv = Record<string, string | undefined>;
+export type ResolveShellCommandOptions = {
+    cwd?: string;
+    env?: ShellCommandEnv;
+    includeStderrInErrors?: boolean;
+    maxOutputBytes?: number;
+    prefix?: string;
+    shell?: readonly [string, ...string[]];
+    stripFinalNewline?: boolean;
+    timeoutMs?: number;
+};
+export declare function resolveShellCommand(value: string, options?: ResolveShellCommandOptions): Promise<string>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@andreas-timm/config",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Bun-first TOML config loading with Zod validation",
     "license": "BSD-2-Clause",
     "author": {
@@ -19,6 +19,7 @@
         "zod"
     ],
     "type": "module",
+    "packageManager": "pnpm@11.9.0",
     "files": [
         "dist",
         "src",
@@ -48,6 +49,8 @@
         "prepack": "bun run build",
         "prepublishOnly": "bun lint && bun test && bun audit --audit-level=moderate",
         "postpack": "bun scripts/postpack.ts",
+        "release": "semantic-release",
+        "release:preview": "node scripts/release-preview.cjs",
         "release:publish": "bun scripts/publish.ts"
     },
     "dependencies": {
@@ -60,14 +63,23 @@
     "devDependencies": {
         "@biomejs/biome": "^2.4.13",
         "@eslint/js": "^10.0.1",
+        "@semantic-release/changelog": "^6.0.3",
+        "@semantic-release/git": "^10.0.1",
+        "@semantic-release/release-notes-generator": "^14.1.0",
         "@types/bun": "^1.3.13",
         "@types/lodash.merge": "^4.6.9",
         "@types/node": "^25.6.0",
         "@typescript-eslint/eslint-plugin": "^8.59.0",
         "@typescript-eslint/parser": "^8.59.0",
+        "eslint": "^10.4.1",
         "globals": "^17.5.0",
         "prettier-plugin-organize-imports": "^4.3.0",
+        "semantic-release": "^25.0.3",
         "typescript": "^5.9.3",
         "zod": "^4.3.6"
+    },
+    "overrides": {
+        "undici@6": "^6.27.0",
+        "undici@7": "^7.28.0"
     }
 }

package/skills/bun-config/SKILL.md

@@ -69,10 +69,30 @@ import { loadConfig } from "@config";
 const config = await loadConfig();
 ```
 
+## Optional Command-Backed Secrets
+
+For TOML values such as:
+
+```toml
+secret = "!pass show secret"
+```
+
+keep `loadConfig()` unchanged and post-process only the known secret field in application code:
+
+```ts
+import { resolveShellCommand } from "@andreas-timm/config";
+
+const config = await loadConfig();
+const secret = await resolveShellCommand(config.secret);
+```
+
+This keeps config loading as plain TOML/Zod validation. Treat values passed to `resolveShellCommand()` as trusted executable input.
+
 ## Behavior
 
 - Files are read in order and deep-merged with `lodash.merge`; later files override earlier ones.
 - Missing files are skipped silently.
 - `root_dir` is injected automatically before schema parsing.
+- Command-backed values such as `secret = "!pass show secret"` stay literal during config loading. Applications can post-process known fields with `resolveShellCommand()`.
 - Validation errors include the resolved file paths and per-issue details.
 - `loadConfig()` caches the promise in module scope, so files are read and parsed only on the first call and concurrent callers share the in-flight load. Call `resetConfig()` to force a reload in tests or after editing a TOML file.

package/src/config.ts

@@ -0,0 +1,22 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function resolveConfigFilePath(
+    rootDir: string,
+    fileName: string,
+): string {
+    if (fileName.startsWith("/")) {
+        return fileName;
+    }
+    if (fileName.startsWith("~")) {
+        const home = homedir();
+        if (fileName === "~") {
+            return home;
+        }
+        if (fileName.startsWith("~/") || fileName.startsWith("~\\")) {
+            return join(home, fileName.slice(2));
+        }
+        return join(home, fileName.slice(1));
+    }
+    return join(rootDir, fileName);
+}

package/src/index.ts

@@ -1,76 +1,3 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
-import merge from "lodash.merge";
-import { concatMap, from, lastValueFrom } from "rxjs";
-import { reduce } from "rxjs/operators";
-import { z } from "zod";
-
-type ConfigData = Record<string, unknown>;
-
-function resolveConfigFilePath(rootDir: string, fileName: string): string {
-    if (fileName.startsWith("/")) {
-        return fileName;
-    }
-    if (fileName.startsWith("~")) {
-        const home = homedir();
-        if (fileName === "~") {
-            return home;
-        }
-        if (fileName.startsWith("~/") || fileName.startsWith("~\\")) {
-            return join(home, fileName.slice(2));
-        }
-        return join(home, fileName.slice(1));
-    }
-    return join(rootDir, fileName);
-}
-
-export async function load<Config>(
-    configSchema: z.ZodType<Config>,
-    rootDir: string,
-    configFiles: string[] = ["global.toml", "local.toml"],
-): Promise<Config> {
-    const config$ = from(configFiles).pipe(
-        concatMap(async (fileName) => {
-            const file = Bun.file(resolveConfigFilePath(rootDir, fileName));
-            if (await file.exists()) {
-                const text = await file.text();
-                return Bun.TOML.parse(text) as ConfigData;
-            }
-            return {};
-        }),
-        reduce((acc, cur) => merge(acc, cur), {} as ConfigData),
-    );
-
-    const merged = await lastValueFrom(config$);
-
-    try {
-        return configSchema.parse({ root_dir: rootDir, ...merged });
-    } catch (err) {
-        if (err instanceof z.ZodError) {
-            const files = configFiles
-                .map((f) => resolveConfigFilePath(rootDir, f))
-                .join(", ");
-            const details = err.issues
-                .map((i) => {
-                    const path = i.path?.length ? i.path.join(".") : "<root>";
-                    const expected =
-                        "expected" in i && i.expected !== undefined
-                            ? `\n  expected: ${i.expected}`
-                            : "";
-                    const received =
-                        "received" in i && i.received !== undefined
-                            ? `\n  received: ${i.received}`
-                            : "";
-                    return `- path: ${path}\n  code: ${i.code}\n  message: ${i.message}${expected}${received}`;
-                })
-                .join("\n");
-            // prettier-ignore
-            const helpful =
-                `From: ${files}\n` +
-                `Computed root_dir: ${rootDir}\n` +
-                `Schema validation issues:\n${details}`;
-            throw new Error(helpful, { cause: err });
-        }
-        throw err;
-    }
-}
+export { load } from "./load";
+export type { ResolveShellCommandOptions } from "./shell";
+export { resolveShellCommand } from "./shell";

package/src/load.ts

@@ -0,0 +1,59 @@
+import merge from "lodash.merge";
+import { concatMap, from, lastValueFrom } from "rxjs";
+import { reduce } from "rxjs/operators";
+import { z } from "zod";
+
+import { resolveConfigFilePath } from "./config";
+
+type ConfigData = Record<string, unknown>;
+
+export async function load<Config>(
+    configSchema: z.ZodType<Config>,
+    rootDir: string,
+    configFiles: string[] = ["global.toml", "local.toml"],
+): Promise<Config> {
+    const config$ = from(configFiles).pipe(
+        concatMap(async (fileName) => {
+            const file = Bun.file(resolveConfigFilePath(rootDir, fileName));
+            if (await file.exists()) {
+                const text = await file.text();
+                return Bun.TOML.parse(text) as ConfigData;
+            }
+            return {};
+        }),
+        reduce((acc, cur) => merge(acc, cur), {} as ConfigData),
+    );
+
+    const merged = await lastValueFrom(config$);
+
+    try {
+        return configSchema.parse({ root_dir: rootDir, ...merged });
+    } catch (err) {
+        if (err instanceof z.ZodError) {
+            const files = configFiles
+                .map((f) => resolveConfigFilePath(rootDir, f))
+                .join(", ");
+            const details = err.issues
+                .map((i) => {
+                    const path = i.path?.length ? i.path.join(".") : "<root>";
+                    const expected =
+                        "expected" in i && i.expected !== undefined
+                            ? `\n  expected: ${i.expected}`
+                            : "";
+                    const received =
+                        "received" in i && i.received !== undefined
+                            ? `\n  received: ${i.received}`
+                            : "";
+                    return `- path: ${path}\n  code: ${i.code}\n  message: ${i.message}${expected}${received}`;
+                })
+                .join("\n");
+            // prettier-ignore
+            const helpful =
+                `From: ${files}\n` +
+                `Computed root_dir: ${rootDir}\n` +
+                `Schema validation issues:\n${details}`;
+            throw new Error(helpful, { cause: err });
+        }
+        throw err;
+    }
+}

package/src/shell.ts

@@ -0,0 +1,168 @@
+type ShellCommandEnv = Record<string, string | undefined>;
+type ShellCommandOutput = {
+    errorOutput: string;
+    exitCode: number | null;
+    output: string;
+    signalCode?: string;
+};
+
+export type ResolveShellCommandOptions = {
+    cwd?: string;
+    env?: ShellCommandEnv;
+    includeStderrInErrors?: boolean;
+    maxOutputBytes?: number;
+    prefix?: string;
+    shell?: readonly [string, ...string[]];
+    stripFinalNewline?: boolean;
+    timeoutMs?: number;
+};
+
+const DEFAULT_SHELL_COMMAND_PREFIX = "!";
+const DEFAULT_SHELL_COMMAND_TIMEOUT_MS = 10_000;
+const DEFAULT_SHELL_COMMAND_MAX_OUTPUT_BYTES = 16 * 1024;
+
+function defaultShell(): readonly [string, ...string[]] {
+    if (process.platform === "win32") {
+        return ["cmd.exe", "/d", "/s", "/c"];
+    }
+    return ["/bin/sh", "-c"];
+}
+
+function stripFinalNewline(value: string): string {
+    return value.replace(/\r?\n$/u, "");
+}
+
+function shellCommandValueError(message: string): Error {
+    return new Error(`Shell command config value ${message}`);
+}
+
+function getCommand(value: string, prefix: string): string | undefined {
+    if (!value.startsWith(prefix) || value.startsWith(prefix + prefix)) {
+        return undefined;
+    }
+
+    const command = value.slice(prefix.length).trimStart();
+    if (command.length === 0) {
+        throw shellCommandValueError("is empty");
+    }
+    return command;
+}
+
+function getLiteralValue(value: string, prefix: string): string {
+    if (value.startsWith(prefix + prefix)) {
+        return value.slice(prefix.length);
+    }
+    return value;
+}
+
+async function readLimitedText(
+    stream: ReadableStream<Uint8Array>,
+    maxBytes: number,
+): Promise<string> {
+    const reader = stream.getReader();
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        size += value.byteLength;
+        if (size > maxBytes) {
+            throw shellCommandValueError(
+                `produced more than ${maxBytes} bytes`,
+            );
+        }
+        chunks.push(value);
+    }
+
+    const output = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(output);
+}
+
+async function runShellCommand(
+    command: string,
+    options: ResolveShellCommandOptions = {},
+): Promise<ShellCommandOutput> {
+    const proc = Bun.spawn({
+        cmd: [...(options.shell ?? defaultShell()), command],
+        cwd: options.cwd,
+        env: options.env,
+        stderr: "pipe",
+        stdin: null,
+        stdout: "pipe",
+        timeout: options.timeoutMs ?? DEFAULT_SHELL_COMMAND_TIMEOUT_MS,
+    });
+    const stdout = readLimitedText(
+        proc.stdout,
+        options.maxOutputBytes ?? DEFAULT_SHELL_COMMAND_MAX_OUTPUT_BYTES,
+    );
+    const stderr = readLimitedText(
+        proc.stderr,
+        options.maxOutputBytes ?? DEFAULT_SHELL_COMMAND_MAX_OUTPUT_BYTES,
+    );
+
+    try {
+        const [output, errorOutput, exitCode] = await Promise.all([
+            stdout,
+            stderr,
+            proc.exited,
+        ]);
+        return {
+            errorOutput,
+            exitCode,
+            output,
+            signalCode: proc.signalCode ?? undefined,
+        };
+    } catch (err) {
+        proc.kill();
+        await Promise.allSettled([stdout, stderr, proc.exited]);
+        throw err;
+    }
+}
+
+function assertSuccessfulCommand(
+    result: ShellCommandOutput,
+    options: ResolveShellCommandOptions,
+): void {
+    if (result.exitCode === 0) {
+        return;
+    }
+
+    const status =
+        result.exitCode === null && result.signalCode
+            ? `terminated by signal ${result.signalCode}`
+            : `failed with exit code ${result.exitCode}`;
+    const stderrDetails =
+        options.includeStderrInErrors && result.errorOutput.trim().length > 0
+            ? `: ${result.errorOutput.trim()}`
+            : "";
+    throw shellCommandValueError(`${status}${stderrDetails}`);
+}
+
+export async function resolveShellCommand(
+    value: string,
+    options: ResolveShellCommandOptions = {},
+): Promise<string> {
+    const prefix = options.prefix ?? DEFAULT_SHELL_COMMAND_PREFIX;
+    if (prefix.length === 0) {
+        throw new Error("Shell command prefix must not be empty");
+    }
+
+    const command = getCommand(value, prefix);
+    if (!command) {
+        return getLiteralValue(value, prefix);
+    }
+
+    const result = await runShellCommand(command, options);
+    assertSuccessfulCommand(result, options);
+    return (options.stripFinalNewline ?? true)
+        ? stripFinalNewline(result.output)
+        : result.output;
+}